sts 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8daa9a90d46149ee4e37d9a02d9cd2e7869ec0633114f051d8c688a602087c7c
-  data.tar.gz: e81526b69471ebcd674384b029e7a7cf182b845223da5fdee1a5d2c033c15e71
+  metadata.gz: 943af3cee1a7418ae0ff90e772ebe61f17b98167bfbd8c5185414709e1ba9ad8
+  data.tar.gz: 642af26133e5a72ec70356e91862ede3e4ca0e4514408d3cc92a3476a9f03270
 SHA512:
-  metadata.gz: 51a330986040cfb8708a1014d6781b2f55ec10662c6ff4f14c6695a9f5b7708ce3b5ce1dc0fd6bae7f757dd3b79880b5914dc46cd5510c70fba0527cdfb601e3
-  data.tar.gz: 40d77a758442401b7b824b27f958dcd39ca77e095778a4400c90632ce036bbffa7d011e80e91f40df5739c5f85b260600a957f76f8d48f32b82d9b50224adb07
+  metadata.gz: 81635f9151d3ce397bc8ae3b22ad5069f7d74801194dc5bd8e3d31188871bb0d0a76099c91a290a16169b390b40fa7d4c4f05576d42f4ef65aa9037828acf88e
+  data.tar.gz: d2596dcb00a143418c828889ff200f3dcf564ff86508862b19ea2575928934a1055c902f08cc430d0cca5d9819f608ac8b77fccb34007d67626824a0d1a5dde3

data/Gemfile

@@ -7,7 +7,6 @@ gemspec
 
 gem "canon"
 gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
-gem "pry"
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/README.adoc

@@ -2,27 +2,193 @@
 
 == Purpose
 
-The `sts` Ruby gem allows you to work with NISO STS (0.2+) and ISOSTS documents.
+The `sts` Ruby gem allows you to work with NISO STS and ISOSTS documents -- two related XML formats for technical standards documents.
 
-NOTE: This is a work-in-progress.
+* **NISO STS** (NISO Z39.96) -- The standardized NISO format for journal and article publishing
+* **ISOSTS** -- The internal precursor format to NISO STS, used by ISO before NISO standardization. ISOSTS adopts TBX (ISO 30042) for terminology markup.
 
-This library now parses the reference
-https://www.iso.org/schema/nisosts/v0.2/doc/tbx/examples/tbx-examples.html[TBX-ISO-TML version 1.1 sample file]
-in the NISO STS format (`tbx-nisosts-0.2.xml`).
+[NOTE]
+This is a work-in-progress.
+
+== Formats Compared
+
+[cols="2,1,1"]
+|===
+| Aspect | NISO STS | ISOSTS
+
+| Standard
+| NISO Z39.96 (NISO standard)
+| Internal format (pre-NISO standardization)
+
+| History
+| Standardized version
+| Original internal format, predates NISO STS
+
+| Root element
+| `<article>`, `<book>`
+| `<standard>`
+
+| Metadata
+| `article-meta`, `journal-meta`
+| `iso-meta`, `reg-meta`, `nat-meta`
+
+| MathML version
+| 3+ (via mml gem)
+| 2 (custom Ruby implementation)
+
+| Math elements
+| `mml:math` + `tex-math`
+| `mml:math` only
+
+| Terminology
+| Inline TBX elements
+| `term-sec` with `tbx:termEntry`
+
+| Standards references
+| Mixed in `ref-list`
+| Dedicated `std`/`std-ref` elements
+
+| Module tree
+| `Sts::NisoSts::*`
+| `Sts::IsoSts::*`
+|===
+
+Despite sharing the same JATS ancestry, the two formats have incompatible content models. Elements with the same XML name (e.g., `p`, `sec`, `disp-formula`) may have different permitted children and attributes. They are implemented as completely separate Ruby class trees.
 
 == Library
 
-=== Usage
+=== Usage: NISO STS
 
 The following code parses a NISO STS XML document.
 
 [source,ruby]
 ----
 require 'sts'
+
 doc = IO.read('spec/fixtures/tbx-nisosts-0.2.xml')
 sts = Sts::NisoSts::Standard.from_xml(doc)
 puts sts.to_xml(pretty: true)
-# => STS file round-tripped
+# => NISO STS file round-tripped
+----
+
+==== NISO STS API
+
+[source,ruby]
+----
+# Parse
+sts = Sts::NisoSts::Standard.from_xml(xml_string)
+
+# Access elements
+sts.front.article_meta.title_wrap.main
+sts.body.sec.first.label
+
+# Serialize back
+sts.to_xml
+sts.to_xml(pretty: true)
+
+# Check document type
+sts.class.name # => "Sts::NisoSts::Standard"
+----
+
+==== NISO STS root classes
+
+* `Sts::NisoSts::Standard` -- Book or article root
+* `Sts::NisoSts::Front` -- Front matter (`article-meta`, `journal-meta`)
+* `Sts::NisoSts::Body` -- Document body
+* `Sts::NisoSts::Back` -- Back matter (references, footnotes)
+
+=== Usage: ISOSTS
+
+ISOSTS uses `<standard>` as the root element and includes MathML 2 for formulae. It adopts TBX (ISO 30042) for terminology sections.
+
+[source,ruby]
+----
+require 'sts'
+
+doc = IO.read('spec/fixtures/iso_sts/feature_doc.xml')
+sts = Sts::IsoSts::Standard.from_xml(doc)
+puts sts.to_xml(pretty: true)
+# => ISOSTS file round-tripped
+----
+
+==== ISOSTS API
+
+[source,ruby]
+----
+# Parse
+sts = Sts::IsoSts::Standard.from_xml(xml_string)
+
+# Access elements
+sts.front.iso_meta.title_wrap.main
+sts.front.iso_meta.std_ident.doc_number
+sts.body.term_sec.first.term_entry.lang_set.first.term
+
+# Serialize back
+sts.to_xml
+sts.to_xml(pretty: true)
+
+# Check document type
+sts.class.name # => "Sts::IsoSts::Standard"
+----
+
+==== ISOSTS root classes
+
+* `Sts::IsoSts::Standard` -- Standard document root (`<standard>`)
+* `Sts::IsoSts::Front` -- Front matter (`iso-meta`, `reg-meta`, `nat-meta`)
+* `Sts::IsoSts::Body` -- Document body (includes `term-sec` for terminology)
+* `Sts::IsoSts::Back` -- Back matter (annexes, references, footnotes)
+
+==== ISOSTS MathML 2
+
+ISOSTS uses MathML 2 (not MathML 3+ like NISO STS). A custom Ruby implementation is provided in `Sts::IsoSts::Mathml2::*`:
+
+[source,ruby]
+----
+# Access MathML 2 content
+disp_formula = sts.body.sec.first.disp_formula
+math = disp_formula.math  # => Sts::IsoSts::Mathml2::Math
+
+# MathML 2 elements
+math.id          # => "mml_1"
+math.display     # => "block" or "inline"
+
+# Serialized as mml:math
+math.to_xml      # => <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" ...>
+----
+
+Available MathML 2 elements: `Math`, `Mrow`, `Mi`, `Mn`, `Mo`, `Mtext`, `Mspace`, `Msub`, `Msup`, `Msubsup`, `Mfrac`, `Msqrt`, `Mroot`, `Mstyle`, `Menclose`, `Mpadded`, `Mphantom`, `Mtable`, `Mtr`, `Mtd`, `Mlabeledtr`, `Mfenced`, `Semantics`, `Annotation`, `AnnotationXml`
+
+==== ISOSTS TBX Terminology
+
+ISOSTS uses TBX (TermBase eXchange, ISO 30042) for terminology sections via `term-sec`:
+
+[source,ruby]
+----
+# Access terminology entries
+term_sec = sts.body.term_sec.first
+term_entry = term_sec.term_entry
+
+term_entry.lang_set.each do |lang_set|
+  puts lang_set.xml_lang        # => "en"
+  puts lang_set.tig.first.term # => "medical device"
+end
+----
+
+TBX elements reuse `Sts::TbxIsoTml::*` classes.
+
+=== TBX Integration
+
+Both NISO STS and ISOSTS support TBX (TermBase eXchange, ISO 30042) for terminology markup. The TBX elements are in the `Sts::TbxIsoTml` module:
+
+[source,ruby]
+----
+require 'sts'
+
+# NISO STS with TBX
+sts = Sts::NisoSts::Standard.from_xml(xml_with_tbx)
+
+# ISOSTS with TBX
+sts = Sts::IsoSts::Standard.from_xml(xml_with_tbx)
 ----
 
 == Credits

data/lib/sts/iso_sts/annex_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class AnnexType < Lutaml::Model::Serializable
+      attribute :content, :string
+      attribute :bold, ::Sts::IsoSts::Bold
+      attribute :italic, ::Sts::IsoSts::Italic
+
+      xml do
+        element "annex-type"
+        mixed_content
+
+        map_content to: :content
+        map_element "bold", to: :bold
+        map_element "italic", to: :italic
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/app.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class App < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :xml_lang, :string
+      attribute :label, ::Sts::IsoSts::Label
+      attribute :annex_type, ::Sts::IsoSts::AnnexType
+      attribute :title, ::Sts::IsoSts::Title
+      attribute :paragraph, ::Sts::IsoSts::Paragraph, collection: true
+      attribute :sec, ::Sts::IsoSts::Sec, collection: true
+      attribute :term_sec, ::Sts::IsoSts::TermSec, collection: true
+      attribute :fn_group, ::Sts::IsoSts::FnGroup, collection: true
+      attribute :ref_list, ::Sts::IsoSts::RefList, collection: true
+      attribute :permissions, ::Sts::NisoSts::Permissions
+      attribute :non_normative_note, ::Sts::IsoSts::NonNormativeNote
+
+      xml do
+        element "app"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "xml:lang", to: :xml_lang
+
+        map_element "label", to: :label
+        map_element "annex-type", to: :annex_type
+        map_element "title", to: :title
+        map_element "p", to: :paragraph
+        map_element "sec", to: :sec
+        map_element "term-sec", to: :term_sec
+        map_element "fn-group", to: :fn_group
+        map_element "ref-list", to: :ref_list
+        map_element "permissions", to: :permissions
+        map_element "non-normative-note", to: :non_normative_note
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/app_group.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class AppGroup < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :xml_lang, :string
+      attribute :label, ::Sts::IsoSts::Label
+      attribute :title, ::Sts::IsoSts::Title
+      attribute :paragraph, ::Sts::IsoSts::Paragraph, collection: true
+      attribute :app, ::Sts::IsoSts::App, collection: true
+      attribute :ref_list, ::Sts::IsoSts::RefList, collection: true
+
+      xml do
+        element "app-group"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "xml:lang", to: :xml_lang
+
+        map_element "label", to: :label
+        map_element "title", to: :title
+        map_element "p", to: :paragraph
+        map_element "app", to: :app
+        map_element "ref-list", to: :ref_list
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/array.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Array < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :specific_use, :string
+      attribute :orientation, :string
+      attribute :xml_lang, :string
+      attribute :originator, :string
+      attribute :label, ::Sts::IsoSts::Label
+      attribute :table, ::Sts::IsoSts::Table
+      attribute :attrib, ::Sts::NisoSts::Attrib, collection: true
+      attribute :permissions, ::Sts::NisoSts::Permissions, collection: true
+
+      xml do
+        element "array"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "orientation", to: :orientation
+        map_attribute "xml:lang", to: :xml_lang
+        map_attribute "originator", to: :originator
+
+        map_element "label", to: :label
+        map_element "table", to: :table
+        map_element "attrib", to: :attrib
+        map_element "permissions", to: :permissions
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/back.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Back < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :app_group, ::Sts::IsoSts::AppGroup, collection: true
+      attribute :ref_list, ::Sts::IsoSts::RefList, collection: true
+      attribute :fn_group, ::Sts::IsoSts::FnGroup, collection: true
+      attribute :sec, ::Sts::IsoSts::Sec, collection: true
+
+      xml do
+        element "back"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+
+        map_element "app-group", to: :app_group
+        map_element "ref-list", to: :ref_list
+        map_element "fn-group", to: :fn_group
+        map_element "sec", to: :sec
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/body.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Body < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :paragraph, ::Sts::IsoSts::Paragraph, collection: true
+      attribute :sec, ::Sts::IsoSts::Sec, collection: true
+      attribute :term_sec, ::Sts::IsoSts::TermSec, collection: true
+      attribute :list, ::Sts::IsoSts::List, collection: true
+      attribute :def_list, ::Sts::IsoSts::DefList, collection: true
+      attribute :disp_formula, ::Sts::IsoSts::DispFormula, collection: true
+      attribute :table_wrap, ::Sts::TbxIsoTml::TableWrap, collection: true
+      attribute :fig, ::Sts::IsoSts::Fig, collection: true
+      attribute :non_normative_note, ::Sts::IsoSts::NonNormativeNote,
+                collection: true
+      attribute :non_normative_example, ::Sts::IsoSts::NonNormativeExample,
+                collection: true
+      attribute :preformat, ::Sts::IsoSts::Preformat, collection: true
+      attribute :styled_content, ::Sts::IsoSts::StyledContent, collection: true
+      attribute :array, ::Sts::IsoSts::Array, collection: true
+      attribute :ref_list, ::Sts::IsoSts::RefList, collection: true
+      attribute :disp_quote, ::Sts::NisoSts::DispQuote, collection: true
+
+      xml do
+        element "body"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+
+        map_element "p", to: :paragraph
+        map_element "sec", to: :sec
+        map_element "term-sec", to: :term_sec
+        map_element "list", to: :list
+        map_element "def-list", to: :def_list
+        map_element "disp-formula", to: :disp_formula
+        map_element "table-wrap", to: :table_wrap
+        map_element "fig", to: :fig
+        map_element "non-normative-note", to: :non_normative_note
+        map_element "non-normative-example", to: :non_normative_example
+        map_element "preformat", to: :preformat
+        map_element "styled-content", to: :styled_content
+        map_element "array", to: :array
+        map_element "ref-list", to: :ref_list
+        map_element "disp-quote", to: :disp_quote
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/bold.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Bold < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :specific_use, :string
+      attribute :content, :string
+      attribute :bold, ::Sts::IsoSts::Bold
+      attribute :italic, ::Sts::IsoSts::Italic
+      attribute :sub, ::Sts::NisoSts::Sub
+      attribute :sup, ::Sts::NisoSts::Sup
+      attribute :xref, ::Sts::TbxIsoTml::Xref
+      attribute :ext_link, ::Sts::NisoSts::ExtLink
+      attribute :uri, ::Sts::NisoSts::Uri
+      attribute :inline_formula, ::Sts::IsoSts::InlineFormula
+      attribute :named_content, ::Sts::NisoSts::NamedContent
+      attribute :styled_content, ::Sts::IsoSts::StyledContent
+      attribute :break, ::Sts::IsoSts::Break
+
+      xml do
+        element "bold"
+        mixed_content
+
+        map_attribute "id", to: :id
+        map_attribute "specific-use", to: :specific_use
+
+        map_content to: :content
+
+        map_element "bold", to: :bold
+        map_element "italic", to: :italic
+        map_element "sub", to: :sub
+        map_element "sup", to: :sup
+        map_element "xref", to: :xref
+        map_element "ext-link", to: :ext_link
+        map_element "uri", to: :uri
+        map_element "inline-formula", to: :inline_formula
+        map_element "named-content", to: :named_content
+        map_element "styled-content", to: :styled_content
+        map_element "break", to: :break
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/break.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Break < Lutaml::Model::Serializable
+      xml do
+        element "break"
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/caption.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Caption < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :specific_use, :string
+      attribute :xml_lang, :string
+      attribute :content_type, :string
+      attribute :style, :string
+      attribute :title, ::Sts::IsoSts::Title
+      attribute :paragraph, ::Sts::IsoSts::Paragraph, collection: true
+      attribute :non_normative_note, ::Sts::IsoSts::NonNormativeNote
+      attribute :non_normative_example, ::Sts::IsoSts::NonNormativeExample
+
+      xml do
+        element "caption"
+
+        map_attribute "id", to: :id
+        map_attribute "specific-use", to: :specific_use
+        map_attribute "xml:lang", to: :xml_lang
+        map_attribute "content-type", to: :content_type
+        map_attribute "style", to: :style
+
+        map_element "title", to: :title
+        map_element "p", to: :paragraph
+        map_element "non-normative-note", to: :non_normative_note
+        map_element "non-normative-example", to: :non_normative_example
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/col.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Col < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :style, :string
+      attribute :span, :string
+      attribute :width, :string
+      attribute :align, :string
+      attribute :char, :string
+      attribute :charoff, :string
+      attribute :valign, :string
+
+      xml do
+        element "col"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "style", to: :style
+        map_attribute "span", to: :span
+        map_attribute "width", to: :width
+        map_attribute "align", to: :align
+        map_attribute "char", to: :char
+        map_attribute "charoff", to: :charoff
+        map_attribute "valign", to: :valign
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/colgroup.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class Colgroup < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :content_type, :string
+      attribute :style, :string
+      attribute :span, :string
+      attribute :width, :string
+      attribute :align, :string
+      attribute :char, :string
+      attribute :charoff, :string
+      attribute :valign, :string
+      attribute :col, ::Sts::IsoSts::Col, collection: true
+
+      xml do
+        element "colgroup"
+
+        map_attribute "id", to: :id
+        map_attribute "content-type", to: :content_type
+        map_attribute "style", to: :style
+        map_attribute "span", to: :span
+        map_attribute "width", to: :width
+        map_attribute "align", to: :align
+        map_attribute "char", to: :char
+        map_attribute "charoff", to: :charoff
+        map_attribute "valign", to: :valign
+
+        map_element "col", to: :col
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/comm_ref.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class CommRef < Lutaml::Model::Serializable
+      attribute :content, :string
+
+      xml do
+        element "comm-ref"
+        mixed_content
+
+        map_content to: :content
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/copyright_holder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class CopyrightHolder < Lutaml::Model::Serializable
+      attribute :content, :string
+      attribute :sub, ::Sts::NisoSts::Sub
+      attribute :sup, ::Sts::NisoSts::Sup
+
+      xml do
+        element "copyright-holder"
+        mixed_content
+
+        map_content to: :content
+        map_element "sub", to: :sub
+        map_element "sup", to: :sup
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/copyright_statement.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class CopyrightStatement < Lutaml::Model::Serializable
+      attribute :content, :string
+      attribute :bold, ::Sts::IsoSts::Bold
+      attribute :italic, ::Sts::IsoSts::Italic
+      attribute :ext_link, ::Sts::NisoSts::ExtLink
+      attribute :uri, ::Sts::NisoSts::Uri
+
+      xml do
+        element "copyright-statement"
+        mixed_content
+
+        map_content to: :content
+        map_element "bold", to: :bold
+        map_element "italic", to: :italic
+        map_element "ext-link", to: :ext_link
+        map_element "uri", to: :uri
+      end
+    end
+  end
+end

data/lib/sts/iso_sts/copyright_year.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Sts
+  module IsoSts
+    class CopyrightYear < Lutaml::Model::Serializable
+      attribute :content, :string
+
+      xml do
+        element "copyright-year"
+
+        map_content to: :content
+      end
+    end
+  end
+end