sts 0.5.3 → 0.5.4

data/GAPS.guidelines.niso-sts-v1.0/06-math-formulae.md

@@ -0,0 +1,128 @@
+# Section 7: Formulae and Equations
+
+## Overview
+Covers display formulae (`<disp-formula>`), inline formulae (`<inline-formula>`), formula groups (`<disp-formula-group>`), formula keys (`<def-list>`), and MathML (`<mml:math>`).
+
+## Element Coverage
+
+### Formula Containers
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<disp-formula>` | Block display formula | `NisoSts::DisplayFormula` | ✅ Supported | In both NisoSts and IsoSts |
+| `<inline-formula>` | Inline formula | `NisoSts::InlineFormula` | ✅ Supported | |
+| `<disp-formula-group>` | Group of formulae | `NisoSts::DispFormulaGroup` | ✅ Supported | |
+
+### Display Formula
+
+| Attribute/Child | Guidelines Usage | In DisplayFormula | Status | Notes |
+|----------------|-----------------|-------------------|--------|-------|
+| `@id` | Formula identifier (formula_1 / for-1) | ✅ Mapped | OK | |
+| `@content-type` | Content type | ✅ Mapped | OK | |
+| `@specific-use` | Specific use | ✅ Mapped | OK | |
+| `<label>` | Formula number "(1)" | ✅ Mapped | OK | |
+| `<math>` (mml:math) | MathML expression | ✅ Via `TbxIsoTml::Math` | OK | |
+| `<graphic>` | Alternative graphic | ✅ Mapped (collection) | OK | |
+| `<preformat>` | Preformatted formula | ✅ Mapped | OK | |
+| `<tex-math>` | TeX math | ✅ Mapped | OK | |
+| `<alternatives>` | Alternative representations | ✅ Mapped | OK | |
+
+### Inline Formula
+
+| Attribute/Child | Guidelines Usage | In InlineFormula | Status | Notes |
+|----------------|-----------------|------------------|--------|-------|
+| `@id` | Formula identifier | ✅ Mapped | OK | |
+| `@content-type` | Content type | ✅ Mapped | OK | |
+| `<math>` (mml:math) | MathML expression | ✅ Via `TbxIsoTml::Math` | OK | |
+| `<alternatives>` | Alternative representations | ✅ Mapped | OK | |
+
+### Formula Group
+
+| Attribute/Child | Guidelines Usage | In DispFormulaGroup | Status | Notes |
+|----------------|-----------------|---------------------|--------|-------|
+| `@id` | Group identifier (forg-informal-X-Y) | ✅ Mapped | OK | |
+| `@content-type` | Content type | ✅ Mapped | OK | |
+| `<label>` | Group label | ✅ Mapped | OK | |
+| `<disp-formula>` | Individual formulae | ✅ Mapped (collection) | OK | |
+| Text between formulae | e.g. ", or" | ⚠️ Needs verification | Mixed content not declared | Guidelines show text between disp-formula children |
+
+### Formula Keys (Section 7.5)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<def-list list-content="formula">` | Formula key | ⚠️ Partial | `DefList` exists but `@list-content` not mapped | |
+| `<label>` "where" | Key label | ✅ Mapped | OK | |
+| `<def-item>` | Key entries | ✅ Mapped | OK | |
+| `<term>` | Variable symbol | ✅ Mapped | OK | |
+| `<def>` | Definition | ✅ Mapped | OK | |
+| `<def-head>` (IEC legacy) | Key heading | ❌ Not mapped | Legacy | IEC legacy uses `<def-head>` instead of `<label>` |
+
+## MathML Coverage
+
+The `TbxIsoTml::Math` model supports the following MathML elements:
+
+| MathML Element | In `TbxIsoTml::Math` | Status | Notes |
+|---------------|---------------------|--------|-------|
+| `@id` | ✅ | OK | |
+| `@display` | ✅ ("block") | OK | |
+| `<mrow>` | ✅ | OK | |
+| `<msub>` | ✅ | OK | |
+| `<msup>` | ✅ | OK | |
+| `<mn>` | ✅ | OK | |
+| `<mo>` | ✅ | OK | |
+| `<mi>` | ✅ | OK | |
+| `<mtext>` | ✅ | OK | |
+| `<mfrac>` | ✅ | OK | |
+| `<mspace>` | ✅ | OK | |
+| `<semantics>` | ✅ | OK | |
+| `<mstyle>` | ✅ | OK | |
+| `<mfenced>` | ✅ | OK | |
+| `<munderover>` | ✅ | OK | |
+
+### MathML Elements Missing from Model
+
+| MathML Element | Guidelines Usage | In Model | Status | Notes |
+|---------------|-----------------|----------|--------|-------|
+| `<munder>` | Under scripts | ✅ `TbxIsoTml::Munder` | OK | Exists as separate class |
+| `<mover>` | Over scripts | ❌ Not in Math | Missing | |
+| `<mtable>` | Math tables | ❌ | Missing | |
+| `<mtr>` | Math table rows | ❌ | Missing | |
+| `<mtd>` | Math table cells | ❌ | Missing | |
+| `<maligngroup>` | Alignment groups | ❌ | Missing | |
+| `<malignmark>` | Alignment marks | ❌ | Missing | |
+| `<mglyph>` | Math glyphs | ❌ | Missing | |
+| `<mlongdiv>` | Long division | ❌ | Missing | |
+| `<mscarries>` | Carries | ❌ | Missing | |
+| `<mscarry>` | Carry | ❌ | Missing | |
+| `<msline>` | Stack line | ❌ | Missing | |
+| `<mstack>` | Stack | ❌ | Missing | |
+| `<menclose>` | Enclosure notation | ❌ | Missing | |
+| `<merror>` | Error message | ❌ | Missing | |
+| `<mmultiscripts>` | Multi-scripts | ❌ | Missing | |
+| `<mprescripts>` | Pre-scripts | ❌ | Missing | |
+| `<msubsup>` | Sub-superscript pair | ❌ | Missing | |
+| `<maction>` | Math action | ❌ | Missing | |
+| `<mpadded>` | Padded space | ❌ | Missing | |
+| `<mphantom>` | Phantom space | ❌ | Missing | |
+| `<annotation>` | Annotation | ❌ | Missing | Part of `<semantics>` |
+| `<annotation-xml>` | XML annotation | ❌ | Missing | Part of `<semantics>` |
+
+## Attribute Gaps
+
+| Attribute | Parent | Guidelines Usage | Modeled | Status |
+|-----------|--------|-----------------|---------|--------|
+| `@list-content` | `<def-list>` | "formula" for formula keys | ❌ Not mapped | Missing |
+
+## Key Gaps
+
+- [ ] **`@list-content` not mapped on `DefList`**: Guidelines use `<def-list list-content="formula">` for formula keys and `<def-list list-content="figure">` for figure keys. This attribute is critical for distinguishing key types. Currently only `@list-type` and `@specific-use` exist.
+
+- [ ] **`<def-head>` (IEC legacy) not supported**: IEC legacy sometimes uses `<def-head>` instead of `<label>` in definition lists.
+
+- [ ] **Text content between `<disp-formula>` in `<disp-formula-group>`**: The guidelines show text like ", or" between formula elements. The `DispFormulaGroup` model does not declare mixed content, so this text would be lost.
+
+- [ ] **MathML coverage is limited**: Only ~16 MathML presentation elements are modeled out of the ~35+ defined in the NISO STS schema. Complex formulae using `<mover>`, `<mtable>`, `<menclose>`, `<mmultiscripts>`, etc. will not round-trip correctly. The guidelines explicitly note "we assume that this will be handled by a specialized WYSIWYG tool" -- but for XML round-tripping, more complete MathML support is needed.
+
+- [ ] **`<annotation>` / `<annotation-xml>` not in `<semantics>`**: The `Semantics` model needs to be checked for completeness.
+
+- [ ] **`<mml:math>` namespace handling**: The MathML elements in guidelines use `mml:` prefix. `TbxIsoTml::Math` uses `namespace ::Sts::Namespaces::MathmlNamespace`. Need to verify that this correctly handles the `mml:math`, `mml:mrow`, etc. prefixed elements.

data/GAPS.guidelines.niso-sts-v1.0/07-references.md

@@ -0,0 +1,113 @@
+# Section 10: References
+
+## Overview
+Covers internal cross-references (`<xref>`), external references (`<std>`, `<mixed-citation>`), footnotes (`<fn>`), URLs (`<uri>`, `<ext-link>`), bibliography structure, and reference elements.
+
+## Element Coverage
+
+### Internal Cross-References (Section 10.1)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<xref>` | Cross-reference element | `TbxIsoTml::Xref` | ✅ Supported | |
+| `@ref-type` | Type of target | ✅ Mapped | OK | Values: app, bibr, disp-formula, fig, fn, list, sec, table, table-fn, other |
+| `@rid` | ID of target | ✅ Mapped | OK | |
+| `<sup>` in `<xref>` | Superscript footnote refs | ✅ Mapped | OK | |
+| `text content` | Reference text | ✅ Mapped | OK | |
+
+### External References (Section 10.2)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<std>` | Reference to a standard | `NisoSts::ReferenceStandard` | ✅ Supported | |
+| `@type` on `<std>` | dated/undated | ✅ Mapped | OK | |
+| `@std-id` on `<std>` | Standard ID | ✅ Mapped | OK | |
+| `<std-ref>` | Standard reference text | `NisoSts::StandardRef` | ✅ Supported | |
+| `<std-id>` in `<std>` | Standard identifier | ✅ Mapped via `StdId` | OK | |
+| `<std-id-group>` | Group of IDs | ✅ Mapped | OK | |
+| `<title>` in `<std>` | Title of referenced standard | ✅ Mapped | OK | |
+| `<mixed-citation>` | Non-standard reference | `NisoSts::MixedCitation` | ✅ Supported | Rich content model |
+| `<uri>` | URL references | `NisoSts::Uri` | ✅ Supported | |
+| `<ext-link>` | External links | `NisoSts::ExtLink` | ✅ Supported | With `@xlink:href` |
+
+### Footnotes (Section 10.1.4)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<fn>` | Footnote content | `NisoSts::Fn`, `TbxIsoTml::Fn` | ✅ Supported | |
+| `@id` on `<fn>` | Footnote ID | ✅ Mapped | OK | |
+| `<label>` in `<fn>` | Footnote label | ✅ Mapped | OK | |
+| `<p>` in `<fn>` | Footnote text | ✅ Mapped | OK | |
+| `<fn-group>` | Footnote group (IEC legacy) | `NisoSts::FnGroup`, `TbxIsoTml::FnGroup` | ✅ Supported | |
+
+### Bibliography (Section 4.4.3)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<ref-list>` | Bibliography container | `NisoSts::ReferenceList` | ✅ Supported | |
+| `@content-type="bibl"` | Bibliography marker | ✅ Mapped | OK | |
+| `@id` | Bibliography ID (sec_bibl / sec-bibliography) | ✅ Mapped | OK | |
+| `<title>` | "Bibliography" | ✅ Mapped | OK | |
+| `<ref>` | Individual reference | `NisoSts::Reference` | ✅ Supported | |
+| `@id` on `<ref>` | Reference ID (biblref_1 / bib-1) | ✅ Mapped | OK | |
+| `<label>` in `<ref>` | Reference label "[1]" | ✅ Mapped | OK | |
+| `<std>` in `<ref>` | Standard reference | ✅ Mapped | OK | |
+| `<mixed-citation>` in `<ref>` | Non-standard reference | ✅ Mapped | OK | |
+| Nested `<ref-list>` | Subdivided bibliography | ✅ Mapped (collection) | OK | |
+| `<non-normative-note>` in `<ref>` | Notes on references | ❌ Not mapped in Reference | Missing | Guidelines show this in Section 4.4.3 |
+
+### Abbreviations (Section 10.1.5)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<def-list list-content="abbreviation">` | Abbreviation list | ⚠️ Partial | DefList exists but `@list-content` not mapped | |
+| `<def-item>` with `@id` | Abbreviation entry | ✅ Mapped (DefItem has `@specific-use` but not `@id`) | ⚠️ Partial | |
+| `<term>` | Abbreviation | ✅ Mapped | OK | |
+| `<def>` | Definition | ✅ Mapped | OK | |
+
+## Attribute Gaps
+
+| Attribute | Parent Element | Guidelines Usage | Modeled | Status |
+|-----------|---------------|-----------------|---------|--------|
+| `@ref-type` on `<xref>` | All cross-references | ✅ | OK | |
+| `@rid` on `<xref>` | Target ID | ✅ | OK | |
+| `@type` on `<std>` | dated/undated | ✅ | OK | |
+| `@std-id-link-type` on `<std-id>` | Link type (urn, id, ooi) | ✅ | OK | |
+| `@std-id-type` on `<std-id>` | ID type (dated, undated) | ✅ | OK | |
+| `@originator` on `<std-id>` | Originating body | ❌ Not mapped | Missing | IEC metadata example shows this |
+| `@xlink:type` on `<mixed-citation>` | XLink type | ✅ | OK | |
+| `@publication-type` on `<mixed-citation>` | Publication type | ✅ | OK | |
+| `@content-type` on `<ref>` | Reference type | ✅ | OK | |
+| `@specific-use` on `<ref>` | IEC delete marker | ❌ Not mapped | Missing | IEC amendments use `@specific-use="delete"` on `<ref>` |
+| `@list-content` on `<def-list>` | "abbreviation" | ❌ Not mapped | Missing | |
+
+## ReferenceStandard Gaps
+
+The `ReferenceStandard` model maps `<std>` content:
+
+| Feature | Guidelines Usage | In ReferenceStandard | Status |
+|---------|-----------------|---------------------|--------|
+| `<std-ref>` | Standard reference text | ✅ | OK |
+| `<title>` | Standard title | ✅ | OK |
+| `<std-id>` | Standard identifier | ✅ Via `StdId` | OK |
+| `<std-id-group>` | ID group | ✅ | OK |
+| `<fn>` | Footnotes | ✅ | OK |
+| `<xref>` | Cross-references | ✅ | OK |
+| `<bold>` | Bold text | ✅ | OK |
+| `<styled-content>` | Styled content | ❌ Not mapped | IEC amendments use `<styled-content specific-use="delete">` inside `<std>` |
+| `<italic>` | Italic text | ❌ Not mapped | May appear in std content |
+| Mixed text content | e.g. ", 7.3.1" after std-ref | ✅ (via mixed_content) | OK |
+
+## Key Gaps
+
+- [ ] **`<non-normative-note>` not mapped in `Reference`**: Guidelines show `<non-normative-note>` inside `<ref>` in normative references (Section 4.3.3 case 2 example with "W3C XML Schema").
+
+- [ ] **`@list-content` not mapped on `DefList`**: Critical for abbreviation lists (Section 10.1.5), formula keys (Section 7.5), and figure keys (Section 8.3).
+
+- [ ] **`@originator` missing on `StdId`**: IEC metadata example shows `<std-id originator="IEC" std-id-link-type="urn" std-id-type="dated">`.
+
+- [ ] **`<styled-content>` not in `ReferenceStandard`**: IEC amendments use `<styled-content specific-use="delete">` and `<styled-content specific-use="insert">` inside `<std>` elements (Section 5.5.1 examples).
+
+- [ ] **`@specific-use` not on `Reference`**: IEC amendments use `<ref specific-use="delete">` to mark deleted references.
+
+- [ ] **`DefItem` missing `@id`**: Abbreviation cross-references use `<def-item id="abb-acsi">` (Section 10.1.5). Currently `DefItem` has `@specific-use` but not `@id`.

data/GAPS.guidelines.niso-sts-v1.0/08-terminology.md

@@ -0,0 +1,127 @@
+# Section 9: Terms and Definitions
+
+## Overview
+Covers terminological entries using TBX (ISO standard) and `<term-display>` (IEC fallback), including `<term-sec>`, `<tbx:termEntry>`, `<tbx:langSet>`, `<tbx:tig>`, `<tbx:term>`, `<tbx:definition>`, `<tbx:note>`, `<tbx:example>`, `<tbx:source>`, `<tbx:entailedTerm>`, `<tbx:see>`, `<tbx:subjectField>`, and `<term-display>`.
+
+## Element Coverage
+
+### Terminological Entry Container
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<term-sec>` | Terminological entry section | `NisoSts::TermSection`, `IsoSts::TermSec` | ✅ Supported | |
+| `@id` on `<term-sec>` | Entry ID (sec_3.1 / con-3.1.3) | ✅ Mapped | OK | |
+| `<label>` in `<term-sec>` | Entry number | ✅ Mapped | OK | |
+| `<tbx:termEntry>` | TBX term entry | `TbxIsoTml::TermEntry` | ✅ Supported | With `@id` |
+| `<term-display>` | Appearance-oriented entry | `NisoSts::TermDisplay` | ✅ Supported | IEC fallback |
+
+### TBX langSet
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<tbx:langSet>` | Language set | `TbxIsoTml::LangSet` | ✅ Supported | |
+| `@xml:lang` on `<tbx:langSet>` | Language | ✅ Mapped (`lang`) | OK | |
+
+### TBX Definition
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<tbx:definition>` | Term definition | `TbxIsoTml::Definition` | ✅ Supported | |
+| `<break/>` in definition | Line break in definition | ⚠️ Needs verification | Definition uses mixed content? | |
+
+### TBX Term Information Group
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<tbx:tig>` | Term information group | `TbxIsoTml::TermInformationGroup` | ✅ Supported | |
+| `@id` on `<tbx:tig>` | TIG identifier | ✅ Mapped | OK | |
+| `<tbx:term>` | Term text | `TbxIsoTml::Term` | ✅ Supported | |
+| `@id` on `<tbx:term>` | Term ID (IEC: ter-sound_pressurep) | ⚠️ Check | Term class exists | |
+| `<tbx:partOfSpeech>` | Part of speech | `TbxIsoTml::PartOfSpeech` | ✅ Supported | With `@value` (noun, verb, adj, adv) |
+| `<tbx:normativeAuthorization>` | Term status | `TbxIsoTml::NormativeAuthorization` | ✅ Supported | With `@value` (preferredTerm, admittedTerm, deprecatedTerm) |
+| `<tbx:termType>` | Term type | `TbxIsoTml::TermType` | ✅ Supported | With `@value` (acronym, abbreviation, fullForm, symbol, formula, equation) |
+| `<tbx:grammaticalNumber>` | Grammatical number | `TbxIsoTml::GrammaticalNumber` | ✅ Supported | |
+| `<tbx:grammaticalGender>` | Grammatical gender | `TbxIsoTml::GrammaticalGender` | ✅ Supported | |
+
+### TBX Notes and Examples
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<tbx:note>` | Notes on terms | `TbxIsoTml::Note` | ✅ Supported | With `@id` |
+| `<tbx:example>` | Examples | `TbxIsoTml::Example` | ✅ Supported | |
+
+### TBX Cross-References
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<tbx:entailedTerm>` | Cross-ref between terms | `TbxIsoTml::EntailedTerm` | ✅ Supported | With `@target` |
+| `@target` | Internal reference | ✅ Mapped | OK | |
+| `@xtarget` | External reference | ⚠️ Check | May not be mapped | Guidelines mention `@xtarget` for external term refs |
+| `<tbx:see>` | Reference to other clauses | `TbxIsoTml::See` | ✅ Supported | With `@target` |
+| `<tbx:crossReference>` | Cross reference | `TbxIsoTml::CrossReference` | ✅ Supported | |
+
+### TBX Source and Subject
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<tbx:source>` | Source of definition | `TbxIsoTml::Source` | ✅ Supported | |
+| `<tbx:subjectField>` | Subject field | `TbxIsoTml::SubjectField` | ✅ Supported | |
+
+### term-display (IEC, Section 9.4)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<term-display>` | Appearance-oriented entry | `NisoSts::TermDisplay` | ✅ Supported | |
+| `<p>` in term-display | Entry text | ✅ Mapped | OK | |
+| `<term>` in term-display | Term | ✅ Via `NisoSts::Term` | OK | But check if `term-display` maps `<term>` -- currently only maps `<p>` and `<non-normative-note>` |
+| `<def>` in term-display | Definition | ❌ Not mapped | Missing | Guidelines show `<def>` inside `<term-display>` |
+| `<list>` in term-display | Lists in definitions | ❌ Not mapped | Missing | |
+| `<xref>` in term-display | Cross-references | ❌ Not mapped | Missing | |
+
+## Attribute Gaps
+
+| Attribute | Parent Element | Guidelines Usage | Modeled | Status |
+|-----------|---------------|-----------------|---------|--------|
+| `@id` on `<tbx:note>` | Note ID (nte-3.1.3-1) | ✅ Mapped | OK | |
+| `@id` on `<tbx:term>` | Term ID (IEC: ter-rated_capacity) | ⚠️ Check | Need to verify `Term` has `@id` | |
+| `@value` on `<tbx:partOfSpeech>` | noun, verb, adj, adv | ✅ Mapped | OK | |
+| `@value` on `<tbx:normativeAuthorization>` | preferredTerm, admittedTerm, deprecatedTerm | ✅ Mapped | OK | |
+| `@value` on `<tbx:termType>` | acronym, abbreviation, fullForm, symbol, formula, equation | ✅ Mapped | OK | |
+| `@target` on `<tbx:entailedTerm>` | Internal term ref | ✅ Mapped | OK | |
+| `@xtarget` on `<tbx:entailedTerm>` | External term ref | ⚠️ Check | May not be mapped | |
+| `@target` on `<tbx:see>` | See target | ✅ Mapped | OK | |
+
+## TermDisplay Content Gaps
+
+The `TermDisplay` model is severely limited. Guidelines Section 9.4 shows rich content:
+
+| Element | In Guidelines `<term-display>` | In TermDisplay model | Status |
+|---------|-------------------------------|---------------------|--------|
+| `<p>` | Paragraph text | ✅ | OK |
+| `<non-normative-note>` | Notes | ✅ | OK |
+| `<term>` | Term text with `@id` | ❌ Not mapped | Missing |
+| `<def>` | Definition with `<p>` children | ❌ Not mapped | Missing |
+| `<list>` | Lists in definition | ❌ Not mapped | Missing |
+| `<xref>` | Cross-references | ❌ Not mapped | Missing |
+| `<label>` | Labels | ❌ Not mapped | Missing |
+| `<styled-content>` | Styled content | ❌ Not mapped | Missing |
+| `<italic>` | Italic text | ❌ Not mapped | Missing |
+| `<fig>` | Figure references | ❌ Not mapped | Missing |
+
+## Key Gaps
+
+- [ ] **`TermDisplay` is severely incomplete**: Only has `<p>` and `<non-normative-note>`. Missing `<term>`, `<def>`, `<list>`, `<xref>`, `<label>`, `<styled-content>`, `<italic>`, `<fig>`. IEC documents that use `<term-display>` (amendments, special series) will lose content.
+
+- [ ] **`<def>` not in `TermDisplay`**: The guidelines (Section 9.4) clearly show `<def><p>...</p></def>` inside `<term-display>`.
+
+- [ ] **`<term>` not in `TermDisplay`**: Guidelines show `<term id="ter-normal_load">normal load</term>` inside `<term-display>`.
+
+- [ ] **`@xtarget` on `EntailedTerm`**: Guidelines mention `@xtarget` for cross-references to terms external to the document. Need to verify this is mapped.
+
+- [ ] **`<std>` inside `<tbx:source>`**: Guidelines show `<tbx:source>SOURCE: <std>...</std></tbx:source>`. Need to verify that the `Source` model supports inline `<std>` elements.
+
+- [ ] **`<tbx:geographicalUsage>` and `<tbx:grammaticalGender>`**: Guidelines note these "will probably be used in the future". Currently modeled (both classes exist), which is good preparation.
+
+- [ ] **`<tbx:pronunciation>`**: Not mentioned heavily in guidelines but exists in `TermInformationGroup`. Acceptable as prepared for future use.
+
+- [ ] **`Section` missing `<term-sec>` children in `IsoSts::Sec`**: `IsoSts::Sec` does have `term_sec` mapped, so this is OK.

data/GAPS.guidelines.niso-sts-v1.0/09-metadata.md

@@ -0,0 +1,113 @@
+# Section A: Metadata Usage
+
+## Overview
+Covers the detailed metadata structures used by ISO (Section A.1), IEC (Section A.2), and National bodies (Section A.3), including specific elements and attributes shown in the complete metadata examples.
+
+## ISO Metadata (Section A.1)
+
+### `<std-meta>` Complete Element Set
+
+| Element | In Guidelines Example | In MetadataStd | Status | Notes |
+|---------|----------------------|---------------|--------|-------|
+| `<title-wrap xml:lang="en">` | Multi-language titles | ✅ Collection | OK | |
+| `<intro>` | Title intro | ✅ | OK | |
+| `<main>` | Title main | ✅ | OK | |
+| `<compl>` | Title complementary | ✅ | OK | |
+| `<full>` | Title full | ✅ | OK | |
+| `<proj-id>` | Project ID | ✅ | OK | |
+| `<release-version>` | DIS/FIS/IS | ✅ | OK | |
+| `<std-ident>` | Standard identification | ✅ | OK | |
+| `<originator>` | ISO/IEC | ✅ | OK | |
+| `<doc-type>` | IS, TR, TS, etc. | ✅ | OK | |
+| `<doc-number>` | Document number | ✅ | OK | |
+| `<part-number/>` | Part number (can be empty) | ✅ | OK | |
+| `<edition>` | Edition number | ✅ | OK | |
+| `<version>` | Version number | ✅ | OK | |
+| `<std-org>` | Standards organization | ✅ | OK | |
+| `@std-org-type` | sdo | ✅ | OK | |
+| `<std-org-abbrev>` | ISO | ✅ | OK | |
+| `<content-language>` | en | ✅ | OK | |
+| `<std-ref type="dated">` | Dated reference | ✅ | OK | |
+| `<std-ref type="undated">` | Undated reference | ✅ | OK | |
+| `<doc-ref>` | ISO/DIS 16936-1(en) | ✅ | OK | |
+| `<comm-ref>` | Committee reference | ✅ | OK | |
+| `<secretariat>` | Secretariat | ✅ | OK | |
+| `<ics>` | ICS code | ✅ | OK | |
+| `<page-count count="8"/>` | Page count | ✅ | OK | |
+| `<std-xref type="revises">` | Cross-reference | ✅ | OK | |
+| `<permissions>` | Copyright | ✅ | OK | |
+| `<copyright-statement>` | Copyright statement | ✅ (string) | OK | |
+| `<copyright-year>` | Copyright year | ✅ | OK | |
+| `<copyright-holder>` | Copyright holder | ✅ | OK | |
+| `<self-uri>` | Self URI | ✅ | OK | |
+| `<custom-meta-group>` | Custom metadata | ✅ | OK | |
+| `<custom-meta>` | Custom metadata entry | ✅ | OK | |
+| `<meta-name>` | Metadata key | ✅ | OK | |
+| `<meta-value>` | Metadata value | ✅ | OK | |
+| `<abstract>` | Abstract | ❌ Not in MetadataStd | Missing | ISO example does NOT show this, but IEC does |
+| `<release-date>` | Release date | ✅ | OK | But ISO example does not show `@date-type` |
+
+## IEC Metadata (Section A.2)
+
+### IEC-Specific Elements in `<std-meta>`
+
+| Element | In Guidelines Example | In MetadataStd | Status | Notes |
+|---------|----------------------|---------------|--------|-------|
+| `<permissions>` with `<license>` | License block | ⚠️ Permissions missing `<license>` | Missing | IEC requires full license text |
+| `<inline-graphic/>` in copyright-statement | Copyright symbol | ❌ copyright-statement is string | Missing | Cannot contain inline-graphic |
+| `<br/>` in copyright-statement | Line break | ❌ copyright-statement is string | Missing | |
+| `<license>` | License block | ❌ Not in Permissions | Missing | |
+| `<license-p>` | License paragraph | ❌ Not in Permissions | Missing | |
+| `<address>` in `<license-p>` | Contact address | ❌ Not available | Missing | |
+| `<addr-line>` in `<address>` | Address line | `NisoSts::AddrLine` exists | OK class but not in permissions context | |
+| `<license_ref>` | License reference URL | ❌ Not in Permissions | Missing | |
+| `<proj-id>` with namespace prefix | "iec:proj:19106" | ✅ | OK | |
+| `<release-version>` | IS | ✅ | OK | |
+| `<std-id-group>` inside `<std-ident>` | Group of IDs | ✅ | OK | |
+| `<std-id>` with `@originator` | Originator attribute | ❌ Not on StdId | Missing | |
+| `<isbn>` in `<std-ident>` | ISBN | ❌ Not in StandardIdentification | Missing | IEC shows `<isbn>9782832263464</isbn>` inside `<std-ident>` |
+| `<suppl-type/>` | Supplement type | ❌ Not in StandardIdentification | Missing | |
+| `<suppl-number/>` | Supplement number | ❌ Not in StandardIdentification | Missing | |
+| `<std-org>` | Organization | ✅ | OK | |
+| `<std-org-abbrev>` | IEC | ✅ | OK | |
+| `<content-language>` | en | ✅ | OK | |
+| `<release-date date-type="published">` | Release date with type | ✅ Has `@date-type` | OK | |
+| `<meta-date type="stability-date">` | Meta date | ✅ Has `@type` | OK | |
+| `<comm-ref>` with `@id` | Committee with ID | ❌ comm-ref is plain string | Missing | IEC: `<comm-ref id="id_1215">TC 25</comm-ref>` |
+| Multiple `<ics>` | Multiple ICS codes | ✅ Collection | OK | |
+| `<counts>` | Counts wrapper | ❌ Not modeled | Missing | IEC: `<counts><page-count count="149"/></counts>` |
+| `<self-uri xlink:type="simple">` | Self URI with xlink type | ✅ Has SelfUri | OK | |
+| `<abstract xml:lang="en">` | Abstract | ❌ Not in MetadataStd | Missing | |
+| `<custom-meta-group>` | Custom metadata | ✅ | OK | |
+
+## National Metadata (Section A.3)
+
+The guidelines mention national metadata can use multiple `<std-meta>` instances. The `NatMeta` class exists and has similar structure to `RegMeta`.
+
+| Feature | In NatMeta | Status | Notes |
+|---------|-----------|--------|-------|
+| `<title-wrap>` | ✅ Collection | OK | |
+| `<std-ident>` | ✅ | OK | |
+| `<permissions>` | ✅ | OK | |
+| `<custom-meta-group>` | ✅ Collection | OK | |
+| `@id` on nat-meta | ❌ Not mapped | Missing | |
+
+## Key Gaps
+
+- [ ] **`<license>` block missing from `Permissions`**: The IEC metadata example (Section A.2) shows a full license block with `<license>`, `<license-p>`, `<address>`, `<addr-line>`, and `<license_ref>`. The `License` and `LicenseP` classes exist but are NOT wired into the `Permissions` model.
+
+- [ ] **`<copyright-statement>` needs rich content**: Currently modeled as plain string. IEC example shows it containing `<inline-graphic/>`, `<br/>`, and mixed text. Needs to be a structured element.
+
+- [ ] **`<copyright-holder>` should be collection**: ISO example shows multiple `<copyright-holder>` elements in a single `<permissions>` block.
+
+- [ ] **`<isbn>` missing from `StandardIdentification`**: IEC example shows `<isbn>` inside `<std-ident>`.
+
+- [ ] **`<suppl-type>`, `<suppl-number>` missing from `StandardIdentification`**: IEC shows these empty elements inside `<std-ident>`.
+
+- [ ] **`<counts>` wrapper not modeled**: IEC uses `<counts><page-count/></counts>` instead of bare `<page-count>`. Neither `MetadataStd` nor `MetadataIso` maps `<counts>`.
+
+- [ ] **`<abstract>` not in metadata models**: IEC shows `<abstract xml:lang="en"><p>...</p></abstract>` inside `<std-meta>`.
+
+- [ ] **`<comm-ref>` should support `@id`**: IEC: `<comm-ref id="id_1215">TC 25</comm-ref>`. Currently plain string.
+
+- [ ] **`@originator` missing from `StdId`**: IEC: `<std-id originator="IEC" std-id-link-type="id" std-id-type="dated">`.

data/GAPS.guidelines.niso-sts-v1.0/10-iso-iec-variant.md

@@ -0,0 +1,141 @@
+# Section 10: ISO-IEC Variant and Amendments
+
+## Overview
+Covers the ISO/IEC-specific features: IEC amendments with `<editing-instruction>`, ISO amendments, IEC Corrigenda, IEC Interpretation Sheets (ISH), IEC Software supplements, and the ID schemes for both IEC and ISO.
+
+## ISO vs IEC Variant Support
+
+### Structural Differences
+
+| Feature | ISO Variant | IEC Variant | sts-ruby Support | Notes |
+|---------|------------|-------------|-----------------|-------|
+| Root element | `<standard>` | `<standard>` | ✅ Both | NisoSts and IsoSts variants |
+| Metadata element | `<iso-meta>` (legacy), `<std-meta>` | `<std-meta>` | ✅ Both | |
+| ID separator | Underscore (`sec_1`) | Dash (`sec-1`) | ✅ Values in `@id` | IDs are free-form strings |
+| `<annex-type>` | Text: "(informative)" | Not rendered (from `@content-type`) | ✅ Both approaches | |
+| `@content-type` on `<app>` | "inform-annex" / "normative-annex" | "inform" / "norm" (legacy), "informative" / "normative" (future) | ✅ Mapped | |
+| `<bold>` in table headers | Yes | No (auto-bold, use `<roman>` for plain) | ✅ Both elements exist | |
+| Footnote placement | At point of use | `<fn-group>` in `<back>` (legacy) | ✅ Both approaches | |
+| Amendment style | Separate text, no semantic instructions | `<editing-instruction>` with types | ⚠️ Partial | EditingInstruction model incomplete |
+| Formula groups | Not used | Used (IEC) | ✅ DispFormulaGroup exists | |
+
+### ID Schemes
+
+#### ISO ID Scheme (from guidelines Annex)
+
+| Element | Pattern | sts-ruby Support | Notes |
+|---------|---------|-----------------|-------|
+| Section: `sec_1`, `sec_1.2.1` | `sec_{number}` | ✅ String IDs | Free-form string attribute |
+| Foreword: `sec_foreword` | `sec_foreword` | ✅ | |
+| Introduction: `sec_intro` | `sec_intro` | ✅ | |
+| Bibliography: `sec_bibl` | `sec_bibl` | ✅ | |
+| Annex: `sec_A`, `sec_B.1` | `sec_{letter}` | ✅ | |
+| Bibliography ref: `biblref_1` | `biblref_{label}` | ✅ | |
+| Term: `term_3.1` | `term_{number}` | ✅ | |
+| Table: `tab_1` | `tab_{number}` | ✅ | |
+| Figure: `fig_1` | `fig_{number}` | ✅ | |
+| Formula: `formula_1` | `formula_{number}` | ✅ | |
+| Footnote: `fn_1` | `fn_{number}` | ✅ | |
+| Table footnote: `table-fn_1.1` | `table-fn_{table}.{n}` | ✅ | |
+
+#### IEC ID Scheme
+
+| Element | Pattern | sts-ruby Support | Notes |
+|---------|---------|-----------------|-------|
+| Section: `sec-1` | `sec-{number}` | ✅ String IDs | |
+| Foreword: `sec-foreword` | `sec-foreword` | ✅ | |
+| Introduction: `sec-introduction` | `sec-introduction` | ✅ | |
+| Bibliography: `sec-bibliography` | `sec-bibliography` | ✅ | |
+| Index: `sec-index` | `sec-index` | ✅ | |
+| Annex: `anx-A` | `anx-{letter}` | ✅ | |
+| Bibliography ref: `bib-1` | `bib-{label or seq}` | ✅ | |
+| Concept: `con-3.2.1` | `con-{number}` | ✅ | |
+| Term entry: `te-3.2.1` | `te-{number}` | ✅ | |
+| Term: `ter-broadcast` | `ter-{term_text}` | ✅ | |
+| Note to entry: `nte-3.4-1` | `nte-{section}-{seq}` | ✅ | |
+| Table: `tab-1` | `tab-{number}` | ✅ | |
+| Informal table: `tab-informal-5.3-1` | `tab-informal-{section}-{seq}` | ✅ | |
+| Figure: `fig-1` | `fig-{number}` | ✅ | |
+| Formula: `for-1` | `for-{number}` | ✅ | |
+| Formula (unnumbered): `for-informal-5.6-1` | `for-informal-{section}-{seq}` | ✅ | |
+| Formula group: `forg-informal-5.3.1-1` | `forg-informal-{section}-{seq}` | ✅ | |
+| Math: `mml-1` | `mml-{seq}` | ✅ | |
+| Footnote: `foo-1` | `foo-{number}` | ✅ | |
+| Symbol footnote: `fos-1` | `fos-{seq}` | ✅ | |
+| Table footnote: `tfn-1-1` | `tfn-{table}-{seq}` | ✅ | |
+| Symbol table fn: `tfs-4-1` | `tfs-{table}-{seq}` | ✅ | |
+| Figure note: `fno-4-1` | `fno-{figure}-{seq}` | ✅ | |
+| Table note: `tno-4-1` | `tno-{table}-{seq}` | ✅ | |
+| List item: `lis-5.6-L1-2` | `lis-{sec}-L{list}-{item}` | ✅ | |
+| Note: `not-3.5-1` | `not-{sec}-{seq}` | ✅ | |
+| Paragraph: `p-450` | `p-{seq}` | ✅ | |
+
+## IEC Amendments (Annex C)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<editing-instruction>` | Amendment instructions | `NisoSts::EditingInstruction` | ⚠️ Partial | Missing `@content-type` and `<p>` child |
+| `@content-type="addition"` | Addition instruction | ❌ Not mapped | Missing | |
+| `@content-type="replacement"` | Replacement instruction | ❌ Not mapped | Missing | |
+| `@content-type="deletion"` | Deletion instruction | ❌ Not mapped | Missing | |
+| `@content-type="modification"` | Modification instruction | ❌ Not mapped | Missing | |
+| `<p>` inside editing-instruction | Instruction text (e.g. "Addition:", "Replace:") | ❌ Not mapped | Missing | Guidelines show `<p><italic>Addition:</italic></p>` |
+| `<italic>` inside editing-instruction `<p>` | Formatting | ❌ Not applicable | Missing because `<p>` not in model | |
+| `<std>` inside editing-instruction | Standard references | ❌ Not applicable | Missing | |
+| `<term-sec>` after editing-instruction | New terms in amendment | ✅ In parent section | OK | |
+
+## ISO Amendments
+
+| Feature | Guidelines Usage | sts-ruby Support | Status | Notes |
+|---------|-----------------|-----------------|--------|-------|
+| Separate document text | No semantic markup | ✅ Sections handle plain text | OK | |
+| TBX terms in amendments | `<term-sec>` with `<tbx:termEntry>` | ✅ | OK | |
+
+## IEC Corrigenda
+
+| Feature | Guidelines Usage | sts-ruby Support | Status |
+|---------|-----------------|-----------------|--------|
+| Integrated into base publication | Content updated inline | N/A | Not a separate XML structure |
+
+## IEC Interpretation Sheets (ISH)
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<supplementary-material>` | Link to ISH PDF | `NisoSts::SupplementaryMaterial` | ✅ Class exists | With `@xlink:href` |
+| `<supplementary-material>` in `<p>` (foreword) | Mentioning ISH inclusion | ❌ Not in Paragraph | Missing | Paragraph does not map `<supplementary-material>` |
+
+## IEC Software Supplements
+
+| Element | Guidelines Usage | sts-ruby Model | Status | Notes |
+|---------|-----------------|---------------|--------|-------|
+| `<supplementary-material xlink:href="asset/...">` | Link to supplement files | ✅ Class exists | OK | |
+| `<supplementary-material>` in `<p>` | In foreword text | ❌ Not in Paragraph | Missing | Same as ISH above |
+
+## Key Gaps
+
+- [ ] **`EditingInstruction` is critically incomplete for IEC amendments**: Missing `@content-type` (values: addition, replacement, deletion, modification) and `<p>` child element. IEC amendments rely entirely on this element.
+
+- [ ] **`<supplementary-material>` not available in `<p>`**: Both IEC ISH and Software supplements need `<supplementary-material>` inside `<p>` in the foreword. `Paragraph` model does not include this element.
+
+- [ ] **`Graphic` missing `id`, `label`, `caption` children for ISO sub-figures**: ISO uses `<graphic id="fig_1.1"><label>a)</label><caption><title>...</title></caption></graphic>` for sub-figure captions. The `Graphic` model only has `@xlink:href` and `<object-id>`.
+
+- [ ] **IEC legacy `<tfoot>` not fully supported**: Legacy IEC tables may use `<tfoot>` element inside `<table>`. `TbxIsoTml::Table` does map `<tfoot>`, so this is OK.
+
+- [ ] **No explicit support for amendment metadata**: Amendments have their own metadata structure (referencing the base publication). No specific amendment metadata model exists beyond standard `<std-meta>`.
+
+- [ ] **`TableWrapFoot` missing legacy `<tr>/<td>` children**: Legacy IEC uses `<tr><td>` directly inside `<table-wrap-foot>`, not currently supported.
+
+## Summary: ISO-IEC Variant Priority Gaps
+
+Priority items for ISO-IEC variant support:
+
+1. **HIGH**: `EditingInstruction` completion (`@content-type`, `<p>` child) -- critical for IEC amendments
+2. **HIGH**: `<supplementary-material>` in `<p>` -- needed for IEC ISH and software supplements
+3. **HIGH**: `<code>` element -- needed for technical standards content
+4. **MEDIUM**: `@list-content` on `DefList` -- needed for formula keys, figure keys, abbreviation lists
+5. **MEDIUM**: `Permissions` completion (`<license>`, rich `<copyright-statement>`) -- needed for IEC metadata
+6. **MEDIUM**: `Graphic` sub-figure support (ISO) -- `id`, `label`, `caption` children
+7. **MEDIUM**: `<index>` element hierarchy -- needed for back matter
+8. **LOW**: MathML element coverage -- partial coverage exists, complex formulae may not round-trip
+9. **LOW**: `<std-doc-meta>` wiring into `Front` -- used in adoption documents
+10. **LOW**: `TermDisplay` completion -- IEC fallback for certain document types