mml 2.2.1 → 2.3.1

data/README.adoc

@@ -47,73 +47,74 @@ math4 = Mml.parse(input, version: 4)
 math.to_xml
 
 # Or use versioned modules directly
-Mml::V3::Math.from_xml(input)
-Mml::V4::Math.from_xml(input)
+Mml::V3.parse(input)
+Mml::V4.parse(input)
 ----
 
 == MathML version architecture
 
-Mml maintains two parallel class hierarchies under `Mml::V3` and `Mml::V4`.
-Both versions share the same namespace URI (`http://www.w3.org/1998/Math/MathML`)
-for backward compatibility.
+Mml maintains three parallel class hierarchies under `Mml::V2`, `Mml::V3`, and `Mml::V4`.
+All versions share the same namespace URI (`http://www.w3.org/1998/Math/MathML`).
 
 [source]
 ----
-                   ┌───────────────────────────────────────────┐
-                   │                   Mml                     │
-                   │  parse() delegates to V3 or V4            │
-                   └────────────────────┬──────────────────────┘
-                                        │
-                    ┌───────────────────┴────────────────────┐
-                    │                                        │
-               ┌────┴────┐                              ┌────┴────┐
-               │ Mml::V3 │                              │ Mml::V4 │
-               └────┬────┘                              └────┬────┘
-                    │                                        │
-    ┌───────────────┼─────────────────────┐  ┌───────────────┼───────────────┐
-    │  ┌────────────┴───────────────┐     │  │  ┌────────────┴────────────┐  │
-    │  │ Element classes            │     │  │  │ Element classes         │  │
-    │  │ (Mi, Mn, Mo, Mrow, ...)    │     │  │  │ (Mi, Mn, Mo, Mrow, ...) │  │
-    │  │                            │     │  │  │ + intent, arg,          │  │
-    │  │ Inherits from              │     │  │  │   displaystyle,         │  │
-    │  │ Lutaml::Model::Serializable│     │  │  │   scriptlevel           │  │
-    │  └────────────┬───────────────┘     │  │  │  + <a> element          │  │
-    │               │                     │  │  └────────────┬────────────┘  │
-    │  ┌────────────┴────────────┐        │  │  ┌────────────┴────────────┐  │
-    │  │ CommonAttributes        │        │  │  │ CommonAttributes        │  │
-    │  │ (child element mixin)   │        │  │  │ (v4 version)            │  │
-    │  └─────────────────────────┘        │  |  └─────────────────────────┘  |
-    └─────────────────────────────────────┘  └───────────────────────────────┘
-                                           │
-                        ┌──────────────────┴──────────────────────┐
-                        │         Lutaml::Model::Serializable     │
-                        │         (XML mapping framework)         │
-                        └─────────────────────────────────────────┘
-----
+                ┌───────────────────────────────────────────┐
+                │                    Mml                    │
+                │   parse() delegates to V2 / V3 / V4       │
+                └────────────────────┬──────────────────────┘
+                                     │
+           ┌─────────────────────────┼─────────────────────────┐
+           │                         │                         │
+      ┌────┴────┐               ┌────┴────┐               ┌────┴────┐
+      │ Mml::V2 │               │ Mml::V3 │               │ Mml::V4 │
+      └────┬────┘               └────┬────┘               └────┬────┘
+           │                         │                         │
+┌──────────┴──────────┐   ┌──────────┴──────────┐   ┌──────────┴──────────┐
+│   V2-only classes   │   │     Shared          │   │   V4-only classes   │
+│ (declare, reln, …)  │   │   Base::modules     │   │ + intent, arg,      │
+└─────────────────────┘   └─────────────────────┘   │   displaystyle,     │
+                                                    │   scriptlevel,      │
+                                                    │   + <a> element     │
+                                                    └─────────────────────┘
+
+                    ┌───────────────────────────────┐
+                    │          lib/mml/base/        │
+                    │     (shared attributes)       │
+                    └───────────────────────────────┘
+----
+
+**V2** (`lib/mml/v2/`): Standalone class hierarchy with full Content MathML support.
+Includes deprecated elements like `declare` and `reln` not present in V3/V4.
+
+**V3** (`lib/mml/v3/`): Uses shared `lib/mml/base/` modules for presentation elements.
+Adds `overflow` attribute and V3-specific features.
+
+**V4** (`lib/mml/v4/`): Uses shared `lib/mml/base/` modules with V4-only attributes
+(`intent`, `arg`, `displaystyle`, `scriptlevel`) and the `<a>` hyperlink element.
 
 === Version selection
 
 [source,ruby]
 ----
 Mml.parse(input)              # Default: MathML 3 (Mml::V3)
+Mml.parse(input, version: 2)  # Explicit MathML 2
 Mml.parse(input, version: 3)  # Explicit MathML 3
-Mml.parse(input, version: 4)  # MathML 4 with intent/arg attributes
+Mml.parse(input, version: 4)  # Explicit MathML 4
+Mml::V2.parse(input)          # Direct v2 parsing
 Mml::V3.parse(input)          # Direct v3 parsing
 Mml::V4.parse(input)          # Direct v4 parsing
 ----
 
-=== Key differences between MathML 3 and MathML 4
+=== Key differences between MathML 2, 3 and 4
 
-[cols="1,2",options="header"]
+[cols="1,2,2",options="header"]
 |===
-|Feature |MathML 4 additions
-|Universal attributes |`intent`, `arg`, `displaystyle`, `scriptlevel` available on all presentation elements
-|New element |`<a>` hyperlink element with `href`, `hreflang`
-|Deprecated (not serialized) a|
-* `fontfamily`, `fontweight`, `fontstyle`, `fontsize`, `color`, `background` on `mstyle`, `mglyph`, `mspace`
-* `groupalign` on `mtable`, `mtr`, `mlabeledtr`
-* `fence`, `separator` on `mo`
-|Deprecated (recognized but hidden) |`<mlabeledtr>`, `<none>` removed from `CommonAttributes` but classes still exist
+|Feature |MathML 3 additions |MathML 4 additions
+|V3-only attributes |`overflow`, `linebreakmultchar` |-
+|V4-universal attributes |- |`intent`, `arg`, `displaystyle`, `scriptlevel`
+|V4 hyperlink element |- |`<a>` with `href`, `hreflang`
+|V2 deprecated elements |`declare`, `reln`, `fn` |`declare`, `reln`, `fn`
+|Deprecated font attrs |`fontfamily`, `fontweight`, etc. |removed from strict V4
 |===
 
 === Migration from previous versions
@@ -128,19 +129,29 @@ namespace:
 # Before (no longer supported)
 require "mml/configuration"
 Mml::Configuration.adapter = :nokogiri
-Mml::Configuration.custom_models = { Mi => MyCustomMi }
+Mml::Configuration.create_context(id: :custom_v3)
 Mml::Math.new(...)
 
 # After — explicit version
 require "mml"
 Mml::V3::Configuration.adapter = :nokogiri
-Mml::V3::Configuration.custom_models = { Mi => MyCustomMi }
-Mml::V3::Math.new(...)
+Mml::V3::Configuration.create_context(
+  id: :custom_v3,
+  substitutions: [
+    { from_type: Mml::V3::Mi, to_type: MyCustomMi }
+  ]
+)
+Mml::V3.parse(input, context: :custom_v3)
 
 # Or for MathML 4
 Mml::V4::Configuration.adapter = :nokogiri
-Mml::V4::Configuration.custom_models = { Mi => MyCustomMi }
-Mml::V4::Math.new(...)
+Mml::V4::Configuration.create_context(
+  id: :custom_v4,
+  substitutions: [
+    { from_type: Mml::V4::Mi, to_type: MyCustomMi }
+  ]
+)
+Mml::V4.parse(input, context: :custom_v4)
 ----
 
 ==== Element class references
@@ -233,7 +244,7 @@ math.to_xml
 
 *v4 only*: `a` (hyperlink)
 
-*Deprecated*: `mlabeledtr`, `none` (classes exist but hidden from CommonAttributes in v4)
+*Deprecated*: `mlabeledtr`, `none` (classes exist but hidden from CommonElements in v4)
 
 === Token elements (leaf nodes)
 
@@ -257,6 +268,7 @@ Container elements hold child elements via `#{tag}_value` collection attributes:
 [source,ruby]
 ----
 Mml::V3::Mrow.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
   mi_value: [Mml::V3::Mi.new(value: "x")],
   mo_value: [Mml::V3::Mo.new(value: "+")],
   mn_value: [Mml::V3::Mn.new(value: "1")],
@@ -271,8 +283,10 @@ Build an expression tree by nesting elements:
 [source,ruby]
 ----
 Mml::V3::Math.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
   mfrac_value: [
     Mml::V3::Mfrac.new(
+      lutaml_register: Mml::V3::Configuration.context_id,
       mi_value: [Mml::V3::Mi.new(value: "a"), Mml::V3::Mi.new(value: "b")],
     ),
   ],
@@ -285,11 +299,19 @@ Mml::V3::Math.new(
 [source,ruby]
 ----
 Mml::V3::Mtable.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
   mtr_value: [
     Mml::V3::Mtr.new(
+      lutaml_register: Mml::V3::Configuration.context_id,
       mtd_value: [
-        Mml::V3::Mtd.new(mi_value: [Mml::V3::Mi.new(value: "a")]),
-        Mml::V3::Mtd.new(mi_value: [Mml::V3::Mi.new(value: "b")]),
+        Mml::V3::Mtd.new(
+          lutaml_register: Mml::V3::Configuration.context_id,
+          mi_value: [Mml::V3::Mi.new(value: "a")]
+        ),
+        Mml::V3::Mtd.new(
+          lutaml_register: Mml::V3::Configuration.context_id,
+          mi_value: [Mml::V3::Mi.new(value: "b")]
+        ),
       ],
     ),
   ],
@@ -301,6 +323,7 @@ Mml::V3::Mtable.new(
 [source,ruby]
 ----
 Mml::V4::A.new(
+  lutaml_register: Mml::V4::Configuration.context_id,
   href: "https://example.com",
   hreflang: "en",
   mi_value: [Mml::V4::Mi.new(value: "click")]
@@ -308,41 +331,141 @@ Mml::V4::A.new(
 # => <a href="https://example.com" hreflang="en"><mi>click</mi></a>
 ----
 
+== MathML V2 Support
+
+V2 is a standalone implementation with its own class hierarchy in `lib/mml/v2/`.
+It includes full Content MathML support with elements not present in V3/V4:
+
+[source,ruby]
+----
+# Parse MathML 2
+Mml::V2.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+
+# Content elements available in V2 (deprecated in V3/V4)
+Mml::V2::Declare.new(...)
+Mml::V2::Reln.new(...)
+Mml::V2::Fn.new(...)
+----
+
+V2 uses `Mml::V2::Configuration` for context management:
+
+[source,ruby]
+----
+Mml::V2::Configuration.context_id  # => :mml_v2
+Mml::V2::Configuration.context
+Mml::V2::Configuration.populate_context!
+----
+
+== MathML V4 Compliance
+
+This implementation has been audited against the
+https://www.w3.org/TR/MathML4/[MathML 4 W3C Recommendation].
+
+=== Universal V4 Attributes
+
+All MathML 4 presentation elements include `intent`, `arg`, `displaystyle`,
+`scriptlevel`, `mathcolor`, and `mathbackground` via the shared
+`Base::V4Attributes` module.
+
+=== Legacy Schema Support
+
+For backwards compatibility with existing MathML content, this gem supports
+both the strict V4 schema and the legacy schema:
+
+[cols="1,2",options="header"]
+|===
+|Feature |Status
+|Universal V4 attributes (`intent`, `arg`, `displaystyle`, `scriptlevel`) |Full support
+|`mathcolor`, `mathbackground` on all presentation elements |Full support
+|`<a>` hyperlink element |Full support
+|Deprecated font attributes (`fontfamily`, `fontweight`, etc.) |Legacy support (V3 + V4 legacy schema)
+|`fence`, `separator` on `<mo>` |Legacy support (removed from default V4 schema)
+|`none` element |Deprecated in V4 (empty `<mrow>` recommended)
+|`mlabeledtr` element |Legacy support (removed from default V4 schema)
+|===
+
+
 == Internal architecture
 
 === Element class patterns
 
-All element classes inherit from `Lutaml::Model::Serializable`:
+Shared attributes and mappings live in `Base::` modules (`lib/mml/base/`).
+V3 and V4 classes include these modules independently — no cross-version inheritance.
+
+* *Leaf elements*: inherit `Lutaml::Model::Serializable`, include `Base::ElementName`
+* *Container elements*: inherit `CommonElements`, include `Base::ElementName`
 
-* *Leaf elements*: use `map_content to: :value` for text content
-* *Container elements*: use `mixed_content` for child elements
+Each element self-registers in its version's built-in `GlobalContext` context.
 
 [source,ruby]
 ----
-# Leaf — text content
-class Mi < Lutaml::Model::Serializable
-  attribute :value, :string
-  xml do
-    element "mi"
-    map_content to: :value
+# Shared attributes (lib/mml/base/mi.rb)
+module Base::Mi
+  def self.included(klass)
+    klass.class_eval do
+      attribute :value, :string
+      xml do
+        element "mi"
+        map_content to: :value
+      end
+    end
   end
 end
 
-# Container — child elements
-class Mrow < Lutaml::Model::Serializable
-  xml do
-    element "mrow"
-    mixed_content
-  end
+# V3 leaf
+class V3::Mi < Lutaml::Model::Serializable
+  include Base::Mi
+end
+
+# V4 leaf — adds V4-only attributes
+class V4::Mi < Lutaml::Model::Serializable
+  include Base::Mi
+  attribute :intent, :string
+end
+
+# V3 container
+class V3::Mrow < CommonElements
+  include Base::Mrow
 end
 ----
 
-=== CommonAttributes
+=== CommonElements
+
+Container elements inherit `CommonElements`, which defines `#{tag}_value` collection
+attributes for all supported child elements. Attribute types use symbols (e.g., `:mi`,
+`:mfrac`) resolved through `Lutaml::Model::GlobalContext`.
+
+V4's `CommonElements` extends the base with the `<a>` hyperlink element.
+
+=== Context and type resolution
+
+When calling `from_xml` directly (outside of `Mml.parse` or `Mml::V3.parse`), pass
+the version-specific context id for correct type resolution.
 
-Container elements that accept arbitrary MathML children import `CommonAttributes`,
-which defines `#{tag}_value` collection attributes for all supported child elements.
-The list of classes that receive this mixin is in
-`Configuration::COMMON_ATTRIBUTES_CLASSES`.
+NOTE: `lutaml-model` still uses the keyword name `register:` in low-level APIs.
+In MML, the value passed to that keyword should be a context id.
+
+[source,ruby]
+----
+Mml::V3::Math.from_xml(input, register: Mml::V3::Configuration.context_id)
+Mml::V4::Math.from_xml(input, register: Mml::V4::Configuration.context_id)
+----
+
+The `parse` methods handle this automatically.
+
+When constructing container elements directly, also pass the context id on the
+instance via `lutaml_register:` so symbolic child types resolve in the right
+versioned context:
+
+[source,ruby]
+----
+math = Mml::V3::Math.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
+  mi_value: [Mml::V3::Mi.new(value: "x")]
+)
+
+math.to_xml
+----
 
 === Namespace
 
@@ -355,19 +478,148 @@ Three input forms are supported:
 
 == Configuration
 
-Configuration is version-specific. Use the namespace matching your target version:
-
 [source,ruby]
 ----
-# Switch XML adapter (default: :ox, also supports :nokogiri)
+# Switch XML adapter (default: :ox, :oga on Opal)
 Mml::V3::Configuration.adapter = :nokogiri
-Mml::V4::Configuration.adapter = :nokogiri
 
-# Register custom model replacements
-Mml::V3::Configuration.custom_models = { Mi => MyCustomMi }
-Mml::V4::Configuration.custom_models = { Mi => MyCustomMi }
+# Access the built-in version-specific contexts
+Mml::V3::Configuration.context_id # => :mml_v3
+Mml::V4::Configuration.context_id # => :mml_v4
+Mml::V3::Configuration.context
+Mml::V4::Configuration.context
+
+# Rebuild a built-in context after an explicit GlobalContext.reset!
+Mml::V3::Configuration.populate_context!
+Mml::V4::Configuration.populate_context!
+
+# Create a derived context with substitutions
+Mml::V3::Configuration.create_context(
+  id: :custom_v3,
+  substitutions: [
+    { from_type: Mml::V3::Mi, to_type: MyCustomMi }
+  ]
+)
+
+# Parse using the custom context
+Mml::V3.parse(input, context: :custom_v3)
+
+# Low-level APIs still use the upstream keyword name `register:`
+Mml::V3::Math.from_xml(input, register: :custom_v3)
 ----
 
+The `context:` keyword is the preferred MML API. The legacy `register:` keyword is
+still accepted temporarily in MML parse methods, but it emits a deprecation warning
+and is normalized to a context id internally.
+
+If you reset global contexts and need the built-in MML contexts restored
+explicitly, call `populate_context!` for the version(s) you want to restore.
+
+== Unsupported Features
+
+The following MathML test suite files are intentionally skipped (not failures) because
+they use features that are not part of the MathML namespace:
+
+[cols="1,3,1",options="header"]
+|===
+|Feature |Reason |Approx. Tests Skipped
+|HTML attributes (`style`, `class`, `id`, `dir`, `mode`, `tabindex`, `data-*`, event handlers) |These are HTML/XML attributes, not MathML attributes |Varies by test suite
+|HTML `<span>` elements |HTML elements are not part of MathML namespace |Varies by test suite
+|XML comments |XML comments inside MathML elements are not supported |Varies by test suite
+|Foreign content in `annotation-xml` |SVG, XHTML content inside annotation-xml is not supported |Varies by test suite
+|Entity references |Named entity references other than standard XML entities |Varies by test suite
+|===
+
+These tests are filtered out via `UNSUPPORTED_PATTERNS` in the test configuration
+and do not represent bugs. They are marked as "pending" in test output because
+RSpec's `skip` directive still records them as pending tests.
+
+== Version-Specific Attributes
+
+Some MathML attributes are version-specific and only available on the appropriate version:
+
+[cols="1,1,2",options="header"]
+|===
+|Attribute |Element |Notes
+|`overflow` |`math` |MathML 3 only (line overflow behavior)
+|`linebreakmultchar` |`math` |MathML 3 only (line break character)
+|`scriptsizemultiplier` |`mscarries` |Float type for fractional scaling
+|===
+
+== Content Elements
+
+The following Content MathML elements are supported for cross-content markup:
+
+* `cn` - numeric content
+* `ci` - identifier content
+* `csymbol` - symbolic content (with presentation element support: `msub`, `msup`, `mrow`, etc.)
+* `cs` - string content
+* `cbytes` - bytes content with encoding attribute
+* `apply`, `bind`, `bvar` - function application and binding
+* `semantics`, `annotation`, `annotation-xml` - semantic annotations
+
+== Test Suite and Fixtures
+
+The gem uses multiple MathML test suites to validate parsing and serialization:
+
+[cols="1,1,3",options="header"]
+|===
+|Test Suite |Version |Description
+|`spec/fixtures/mml2-testsuite/` |V2 |W3C MathML 2 test suite with Content and Presentation elements
+|`spec/fixtures/mml3-testsuite/` |V3 |W3C MathML 3 test suite
+|`spec/fixtures/mmlcore-testsuite/` |V4 |WPT MathML Core tests (modern browser implementation)
+|`spec/fixtures/v2/`, `spec/fixtures/v4/` |V2/V4 |Hand-crafted fixtures for version-specific features
+|===
+
+=== Running Tests
+
+[source,bash]
+----
+bundle exec rake        # Run all specs + rubocop
+bundle exec rspec       # Run all tests
+bundle exec rspec spec/mml/v3_spec.rb  # Run specific test file
+bundle exec rspec --only-failures       # Run only previously failing tests
+----
+
+=== Test Fixture Processing
+
+Some test suites require preprocessing to extract clean MathML from HTML wrappers:
+
+[source,bash]
+----
+# Preprocess test fixtures (strips HTML wrappers, extracts MathML)
+rake spec:preprocess_fixtures
+
+# Validate preprocessed fixtures against XSD schemas
+rake spec:validate_cleaned_fixtures
+
+# Both in sequence
+rake spec:prepare
+----
+
+The preprocessed fixtures are stored in `tmp/cleaned_fixtures/` and are excluded from git.
+
+=== Unsupported Test Patterns
+
+Tests are filtered via `UNSUPPORTED_PATTERNS` when they contain:
+
+* HTML elements/attributes (`<span>`, `style=`, `class=`, etc.)
+* XML comments inside elements
+* Foreign content (SVG in `annotation-xml`)
+* Entity references not handled by the parser
+* Content elements not supported in presentation context (V3/V4)
+
+These are marked as pending, not failures, because they represent features outside the MathML namespace.
+
+=== Known Pending Issues
+
+[cols="1,3",options="header"]
+|===
+|Issue |Affected Tests
+|lutaml-model Unicode NCR comparison |V2 tests with `&#x02009;` spacing characters
+|Parser schema validation |V3 ErrorHandling tests (parser accepts invalid MathML)
+|===
+
 == Development
 
 [source,bash]

data/Rakefile

@@ -6,7 +6,22 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
-
 RuboCop::RakeTask.new
 
+# Spec preparation tasks
+namespace :spec do
+  desc "Preprocess MathML fixture files to clean them"
+  task :preprocess_fixtures do
+    load "spec/tasks/preprocess_fixtures.rb"
+  end
+
+  desc "Validate cleaned fixtures against XSD schemas"
+  task :validate_cleaned_fixtures do
+    load "spec/tasks/validate_cleaned_fixtures.rb"
+  end
+
+  desc "Prepare spec fixtures (preprocess + validate)"
+  task prepare: %i[preprocess_fixtures validate_cleaned_fixtures]
+end
+
 task default: %i[spec rubocop]

data/lib/mml/base/content/annotation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mml
+  module Base
+    module Content
+      # annotation is a non-XML annotation for semantic markup.
+      # Used within semantics element.
+      module Annotation
+        def self.included(klass)
+          klass.class_eval do
+            attribute :definition_url, :string
+            attribute :encoding_value, :string
+            attribute :href, :string
+            attribute :value, :string
+
+            xml do
+              namespace Mml::Namespace
+              element "annotation"
+
+              map_content to: :value
+              map_attribute "href", to: :href
+              map_attribute "definitionURL", to: :definition_url
+              map_attribute "encoding", to: :encoding_value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mml/base/content/annotation_xml.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mml
+  module Base
+    module Content
+      # annotation-xml is an XML-encoded annotation for semantic markup.
+      # Used within semantics element to embed presentation or other markup.
+      module AnnotationXml
+        def self.included(klass)
+          klass.class_eval do
+            attribute :definitionURL, :string
+            attribute :annotation_xml_encoding, :string
+            attribute :cd, :string
+            attribute :name, :string
+
+            xml do
+              namespace Mml::Namespace
+              element "annotation-xml"
+              mixed_content
+
+              map_attribute "definitionURL", to: :definitionURL
+              map_attribute "encoding", to: :annotation_xml_encoding
+              map_attribute "cd", to: :cd
+              map_attribute "name", to: :name
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mml/base/content/apply.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mml
+  module Base
+    module Content
+      # The apply element applies a function to its arguments.
+      # First child is the operator, remaining children are operands.
+      module Apply
+        def self.included(klass)
+          klass.class_eval do
+            attribute :definition_url, :string
+            attribute :encoding_value, :string
+
+            xml do
+              namespace Mml::Namespace
+              element "apply"
+              mixed_content
+
+              map_attribute "definitionURL", to: :definition_url
+              map_attribute "encoding", to: :encoding_value
+            end
+          end
+        end
+      end
+    end
+  end
+end