relaton-bib 2.0.0.pre.alpha.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 926f3fc5e7c7087fdb474ef99b675f180a83aa3d6ceb33bae1be4bfe35809af8
-  data.tar.gz: 8f9320d9910d88ae20f20883087251a11cd2f192751709574d509cfb79f79918
+  metadata.gz: f0dda50ff6033e0640ffeb6e18596373c644c9704206159f4447a5ccc7f8ec4b
+  data.tar.gz: 2d0d134b521224759c9636fbb3aff0f283ec6028a22e8bc0e554aa3795dcdc1a
 SHA512:
-  metadata.gz: d4276b3adfde5ba25a78e1de55c5ed6fea48358076ed5c3f18b6e1f4b5afb517b144145429ffe05127ba1fdf6670c91c0b8b4a8f5ebecc739a7f89edbcb8b339
-  data.tar.gz: a67e4932c74fcd648d2b2c4bebfacf8534684d0525909a9fa4c96626890b475593264faa3bc864d6a1a5c2786c99d26a5f71e7b0dd49f404530f5763d154832e
+  metadata.gz: cfaa4b06692c17d90018c4e54f5efaa91be82f49be3008730a46814433bf2f2dcd7ff3541b2369bf898401b620bbd19adad1752232e3b5a6eeb1ec3ab2914a38
+  data.tar.gz: ff217c62b41988af9300bf4dfafd1c469d76254dd2c9402199b0d88418c23c8d7e020ca069b4074cb1d0909fdb57abdd8a0391eb855b9d8d1528548050313caf

data/.gitignore

@@ -11,5 +11,7 @@
 
 # rspec failure tracking
 .rspec_status
-.rubocop-https---raw-githubusercontent-com-riboseinc-oss-guides-master-ci-rubocop-yml
 Gemfile.lock
+.claude/
+.rubocop-remote-87c7cdd254a8d09d005ee06efac7acc0.yml
+rubocop-87c7cdd254a8d09d005ee06efac7acc0.yml

data/.rubocop.yml

@@ -7,6 +7,6 @@ require: rubocop-rails
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
 Rails:
   Enabled: false

data/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+RelatonBib is a Ruby gem that implements the [BibliographicItem model](https://github.com/metanorma/relaton-models#bibliography-uml-models) for bibliographic reference management. It's part of the Relaton ecosystem and serves as the base library for other Relaton gems.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/relaton_bib/bibliographic_item_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton_bib/bibliographic_item_spec.rb:42
+
+# Run linting
+bundle exec rubocop
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+
+# Interactive console
+bin/console
+```
+
+## Architecture
+
+### Serialization Layer (lutaml-model)
+
+The codebase uses [lutaml-model](https://github.com/lutaml/lutaml-model) for serialization. Each model class in `lib/relaton/bib/model/` inherits from `Lutaml::Model::Serializable` and declares attributes with XML/YAML/JSON mappings.
+
+### Core Classes
+
+**`Relaton::Bib::Item`** ([lib/relaton/bib/model/item.rb](lib/relaton/bib/model/item.rb)) - The main serialization class defining all bibliographic attributes and their XML mappings. Uses `ItemData` as its underlying model.
+
+**`Relaton::Bib::ItemData`** ([lib/relaton/bib/item_data.rb](lib/relaton/bib/item_data.rb)) - The data container class that holds bibliographic data and provides conversion methods (`to_xml`, `to_yaml`, `to_bibtex`, `to_rfcxml`). This separation allows the same data to be serialized differently (bibitem vs bibdata).
+
+**`Relaton::Bib::Bibitem`** and **`Relaton::Bib::Bibdata`** - Variants of `Item` with different XML root elements and attributes (bibitem excludes `ext`, bibdata excludes `id`).
+
+### Component Models
+
+Each bibliographic attribute has its own class in `lib/relaton/bib/model/`:
+
+- `Title`, `LocalizedString`, `LocalizedMarkedUpString` - text with language/script
+- `Contributor`, `Person`, `Organization` - contributors and affiliations
+- `Docidentifier` - document IDs (DOI, ISBN, etc.)
+- `Date` - publication dates with custom `StringDate` type
+- `Relation` - related documents (circular reference with Item)
+- `Ext` - extension data (doctype, ICS codes, structured identifiers)
+
+### Parsing
+
+- **`HashParserV1`** ([lib/relaton/bib/hash_parser_v1.rb](lib/relaton/bib/hash_parser_v1.rb)) - Converts legacy Hash/YAML format to `ItemData`
+- **`Converter::BibXml`** ([lib/relaton/bib/converter/bibxml.rb](lib/relaton/bib/converter/bibxml.rb)) - Parses RFC BibXML format via `Relaton::Bib::Converter::BibXml.to_item`
+- **lutaml-model native** - `Item.from_xml`, `Item.from_yaml`, `Item.from_json` handle current format
+
+### Rendering
+
+- **`Renderer::BibtexBuilder`** - Converts `ItemData` to BibTeX format
+- **`Converter::BibXml`** - Converts `ItemData` to RFC XML format via `Relaton::Bib::Converter::BibXml.to_xml`
+- **lutaml-model native** - `to_xml`, `to_yaml`, `to_json` via the serialization classes
+
+### Usage Pattern
+
+```ruby
+# Parse from YAML
+item = Relaton::Bib::Item.from_yaml(yaml_string)
+
+# Parse from XML
+item = Relaton::Bib::Bibitem.from_xml(xml_string)
+item = Relaton::Bib::Bibdata.from_xml(xml_string)
+
+# Parse from RFC XML
+item = Relaton::Bib::Converter::BibXml.to_item(xml_string)
+
+# Convert to different formats (returns string)
+item.to_xml                    # as <bibitem>
+item.to_xml(bibdata: true)     # as <bibdata>
+item.to_yaml
+item.to_bibtex
+item.to_rfcxml
+```
+
+## Code Style
+
+- Follows Ribose OSS Ruby style guide (inherited via `.rubocop.yml`)
+- Target Ruby version: 3.1+
+- Uses YARD documentation comments

data/Gemfile

@@ -5,6 +5,7 @@ gemspec
 
 gem "byebug"
 gem "equivalent-xml", "~> 0.6"
+gem "openssl", "~> 3.3.2" # 3.3.0 raises error when rubocop fetches https resources
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 gem "rubocop"

data/README.adoc

@@ -180,7 +180,7 @@ Relaton::Bib::Item.from_yaml yaml
 xml = File.read 'spec/fixtures/rfc.xml'
  => "<reference anchor=\"RFC1\" target=\"10.17487/RFC0001\">\n  <front>\n    <title>Title RFC1</title>\n    <seriesInf..."
 
-Relaton::Bib::Parser::RfcReference.from_xml xml
+Relaton::Bib::Converter::BibXml.to_item xml
  => #<Relaton::Bib::ItemData:0x000000011dc9fc98 ...
 ----
 
@@ -202,7 +202,7 @@ item = Relaton::Bib::Bibdata.from_xml xml
 
 [source,ruby]
 ----
-Relaton::Bib::BibtexParser.from_bibtex File.read('spec/examples/techreport.bib')
+Relaton::Bib::BibtexParser.from_bibtex File.read('spec/fixtures/techreport.bib')
 => {"ISOTC211"=>
   #<Relaton::Bib::Item:0x007fedee0a2ab0
   ...
@@ -221,6 +221,18 @@ formattedref: ISO 123:1994
 ...
 ----
 
+=== Export bibliographic item to Hash
+
+[source,ruby]
+----
+item.to_h
+=> {"id"=>"ISO1231994",
+ "type"=>"standard",
+ "schema_version"=>"...",
+ "title"=>[...],
+ ...}
+----
+
 === Export bibliographic item to BibTeX
 
 [source,ruby]

data/grammars/basicdoc.rng

@@ -187,6 +187,15 @@ Applicable to modify and delete</a:documentation>
         <a:documentation>Optional caption of this block</a:documentation>
       </attribute>
     </optional>
+    <optional>
+      <attribute name="position">
+        <a:documentation>For an "add" change, whether the change is added before or after the location</a:documentation>
+        <choice>
+          <value>before</value>
+          <value>after</value>
+        </choice>
+      </attribute>
+    </optional>
     <optional>
       <element name="location">
         <a:documentation>The location(s) in the original document which have undergone the change described in this block</a:documentation>
@@ -198,21 +207,25 @@ Applicable to modify and delete</a:documentation>
         </zeroOrMore>
       </element>
     </optional>
-    <optional>
+    <zeroOrMore>
       <element name="description">
-        <a:documentation>Description of the change described in this block</a:documentation>
-        <zeroOrMore>
+        <a:documentation>Description(s) of the change described in this block</a:documentation>
+        <oneOrMore>
           <ref name="BasicBlock"/>
-        </zeroOrMore>
+        </oneOrMore>
       </element>
-    </optional>
+    </zeroOrMore>
     <optional>
       <element name="newcontent">
-        <a:documentation>New content to be added to the document; applicable to add and modify</a:documentation>
+        <a:documentation>New content to be added to the document; applicable to add and modify.
+Can be blocks and/or sections</a:documentation>
         <ref name="OptionalId"/>
         <zeroOrMore>
           <ref name="BasicBlock"/>
         </zeroOrMore>
+        <zeroOrMore>
+          <ref name="section"/>
+        </zeroOrMore>
       </element>
     </optional>
     <zeroOrMore>
@@ -267,6 +280,10 @@ in a document (e.g. sourcecode annotations)</a:documentation>
       <value>justified</value>
     </choice>
   </define>
+  <define name="IdRefType">
+    <a:documentation>Type of cross-references to elements. In BasicDoc, these always point to id { xsd:ID } </a:documentation>
+    <data type="IDREF"/>
+  </define>
   <define name="RequiredId">
     <a:documentation>Mandatory anchor of element, to be used for cross-references within the document</a:documentation>
     <attribute name="id">
@@ -382,33 +399,7 @@ in a document (e.g. sourcecode annotations)</a:documentation>
     <a:documentation>Block intended to capture reviewer comments about some text in the document</a:documentation>
     <element name="review">
       <ref name="RequiredId"/>
-      <attribute name="reviewer">
-        <a:documentation>The party who has offered the comment</a:documentation>
-      </attribute>
-      <optional>
-        <attribute name="type">
-          <a:documentation>The type of reviewer comment</a:documentation>
-        </attribute>
-      </optional>
-      <optional>
-        <attribute name="date">
-          <a:documentation>The date when the comment was made</a:documentation>
-          <data type="dateTime"/>
-        </attribute>
-      </optional>
-      <optional>
-        <attribute name="from">
-          <a:documentation>Identifier for the start of the text or point in the text to which the comment applies.
-If not provided, the comment applies in the vicinity of the place it has been inserted into the text</a:documentation>
-          <data type="IDREF"/>
-        </attribute>
-      </optional>
-      <optional>
-        <attribute name="to">
-          <a:documentation>Identifier for the end of the text to which the comment applies</a:documentation>
-          <data type="IDREF"/>
-        </attribute>
-      </optional>
+      <ref name="ReviewAttributes"/>
       <oneOrMore>
         <ref name="paragraph">
           <a:documentation>Reviewer comments content</a:documentation>
@@ -416,6 +407,35 @@ If not provided, the comment applies in the vicinity of the place it has been in
       </oneOrMore>
     </element>
   </define>
+  <define name="ReviewAttributes">
+    <attribute name="reviewer">
+      <a:documentation>The party who has offered the comment</a:documentation>
+    </attribute>
+    <optional>
+      <attribute name="type">
+        <a:documentation>The type of reviewer comment</a:documentation>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="date">
+        <a:documentation>The date when the comment was made</a:documentation>
+        <data type="dateTime"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="from">
+        <a:documentation>Identifier for the start of the text or point in the text to which the comment applies.
+If not provided, the comment applies in the vicinity of the place it has been inserted into the text</a:documentation>
+        <ref name="IdRefType"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="to">
+        <a:documentation>Identifier for the end of the text to which the comment applies</a:documentation>
+        <ref name="IdRefType"/>
+      </attribute>
+    </optional>
+  </define>
   <define name="NumberingAttributes">
     <optional>
       <attribute name="unnumbered">
@@ -857,6 +877,7 @@ in case the table cannot be rendered accessibly (HTML 5)</a:documentation>
   <define name="tr">
     <a:documentation>Sequence of cells to be displayed as a row in a table</a:documentation>
     <element name="tr">
+      <ref name="TrAttributes"/>
       <oneOrMore>
         <choice>
           <ref name="td">
@@ -869,6 +890,9 @@ in case the table cannot be rendered accessibly (HTML 5)</a:documentation>
       </oneOrMore>
     </element>
   </define>
+  <define name="TrAttributes">
+    <empty/>
+  </define>
   <define name="tr-no-id">
     <a:documentation>Sequence of cells to be displayed as a row in a table: optional ID attributes recursively (for use in Relaton, metadata)</a:documentation>
     <element name="tr">
@@ -1280,13 +1304,13 @@ Restricted recursively to contain only other such inline elements with no identi
       <ref name="pure_strike"/>
       <ref name="pure_smallcap"/>
       <ref name="br"/>
+      <ref name="stem"/>
     </choice>
   </define>
   <define name="NestedTextElement">
     <a:documentation>Contents of TextElement tags: leaves out tags that should occur only at top level of block: bookmark image hr pagebreak</a:documentation>
     <choice>
       <ref name="PureTextElement"/>
-      <ref name="stem"/>
       <ref name="eref"/>
       <ref name="xref"/>
       <ref name="hyperlink"/>
@@ -1497,7 +1521,7 @@ Restricted recursively to contain only other such inline elements with no identi
         <attribute name="to">
           <a:documentation>A reference to an anchor element (typically a bookmark), 
 to indicate that the index range covers a range of locations between the current index element and the `to` anchor</a:documentation>
-          <data type="IDREF"/>
+          <ref name="IdRefType"/>
         </attribute>
       </optional>
       <ref name="index-primary">
@@ -1655,7 +1679,7 @@ which can be bookmarks as well as block or section references</a:documentation>
   <define name="XrefAttributes">
     <attribute name="target">
       <a:documentation>The identifier of a section, block or inlined element being referenced</a:documentation>
-      <data type="IDREF"/>
+      <ref name="IdRefType"/>
     </attribute>
     <optional>
       <attribute name="type">
@@ -1694,23 +1718,29 @@ which can be bookmarks as well as block or section references</a:documentation>
     <a:documentation>Inline reference to a paragraph or paragraphs, appearing as a footnote.
 The target of a footnote is the location it is embedded in within the text</a:documentation>
     <element name="fn">
-      <attribute name="reference">
-        <a:documentation>The number of the footnote, used to identify it visually</a:documentation>
-      </attribute>
-      <oneOrMore>
-        <ref name="paragraph">
-          <a:documentation>The content of the footnote</a:documentation>
-        </ref>
-      </oneOrMore>
+      <ref name="FnAttributes"/>
+      <ref name="FnBody"/>
     </element>
   </define>
+  <define name="FnBody">
+    <oneOrMore>
+      <ref name="paragraph">
+        <a:documentation>The content of the footnote</a:documentation>
+      </ref>
+    </oneOrMore>
+  </define>
+  <define name="FnAttributes">
+    <attribute name="reference">
+      <a:documentation>The number of the footnote, used to identify it visually</a:documentation>
+    </attribute>
+  </define>
   <define name="callout">
     <a:documentation>Inline reference to a paragraph or paragraphs, appearing as annotation of source code</a:documentation>
     <element name="callout">
       <attribute name="target">
         <a:documentation>The target of the callout is understood to be the location of the callout within the source code; 
 the extent of the target is not expressed overtly</a:documentation>
-        <data type="IDREF"/>
+        <ref name="IdRefType"/>
       </attribute>
       <text>
         <a:documentation>The label of the callout, used to identify its target within the source code</a:documentation>

data/grammars/biblio-standoc.rng

@@ -1,13 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0">
-  <!--
-    Add-ons to biblio.rnc for standoc model: defines the extension point BibDataExtensionType
-    of relaton
-    
-    Specialisations as for biblio.rnc. Extension point can be redefined completely for a flavour of standoc
-    (SDO); but other elements in Bibdata can only be extended (more specialised vocabularies for Bibdata)
-  -->
   <include href="biblio.rng">
+    <!-- ALERT: we cannot have comments on root element, as they intervene with https://github.com/metanorma/metanorma/issues/437 fix -->
+    <!--
+      Add-ons to biblio.rnc for standoc model: defines the extension point BibDataExtensionType
+      of relaton
+      
+      Specialisations as for biblio.rnc. Extension point can be redefined completely for a flavour of standoc
+      (SDO); but other elements in Bibdata can only be extended (more specialised vocabularies for Bibdata)
+    -->
     <define name="BibData">
       <a:documentation>The bibliographic description of a standardisation document</a:documentation>
       <ref name="StandardBibliographicItem"/>
@@ -75,12 +76,6 @@ from other documents in the same doctype</a:documentation>
     <ref name="flavor">
       <a:documentation>Flavour of Metanorma used to process this document</a:documentation>
     </ref>
-    <optional>
-      <ref name="editorialgroup">
-        <a:documentation>Groups associated with the production of the standards document, typically within
-a standards definition organization</a:documentation>
-      </ref>
-    </optional>
     <zeroOrMore>
       <ref name="ics">
         <a:documentation>Classification of the document contents taken from the International Classification of Standards</a:documentation>
@@ -91,6 +86,9 @@ a standards definition organization</a:documentation>
         <a:documentation>Representation of the identifier for the standardisation document, giving its individual semantic components</a:documentation>
       </ref>
     </zeroOrMore>
+    <ref name="DocumentImages">
+      <a:documentation>Coverpage and other images to be rendered with document</a:documentation>
+    </ref>
   </define>
   <define name="doctype">
     <a:documentation>Classification of the standardisation document</a:documentation>
@@ -126,49 +124,6 @@ a standards definition organization</a:documentation>
 However we prefer not to hardcode it, given ongoing extension.</a:documentation>
     <text/>
   </define>
-  <define name="editorialgroup">
-    <a:documentation>A group associated with the production of the standards document, typically within
-a standards definition organization</a:documentation>
-    <element name="editorialgroup">
-      <oneOrMore>
-        <ref name="technical-committee">
-          <a:documentation>A technical committee associated with the production of the standards document</a:documentation>
-        </ref>
-      </oneOrMore>
-    </element>
-  </define>
-  <define name="technical-committee">
-    <a:documentation>Technical committee associated with the production of a standards document</a:documentation>
-    <element name="technical-committee">
-      <ref name="IsoWorkgroup"/>
-    </element>
-  </define>
-  <define name="IsoWorkgroup">
-    <optional>
-      <attribute name="number">
-        <a:documentation>Numeric identifier of the technical committee</a:documentation>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="type">
-        <a:documentation>Type of the technical committee, used in identifying the technical committee</a:documentation>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="identifier">
-        <a:documentation>Non-numeric, complete identifier of the technical committee</a:documentation>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="prefix">
-        <a:documentation>Disambiguating prefix added to number to form the identifier of the technical committee,
-typically indicating its type</a:documentation>
-      </attribute>
-    </optional>
-    <text>
-      <a:documentation>Name of the technical committee</a:documentation>
-    </text>
-  </define>
   <define name="ics">
     <a:documentation>Classification taken from the International Classification of Standards. 
 ICS is defined by ISO here -- https://www.iso.org/publication/PUB100033.html</a:documentation>
@@ -268,6 +223,32 @@ and not those document components</a:documentation>
       </optional>
     </element>
   </define>
+  <define name="DocumentImages">
+    <zeroOrMore>
+      <element name="coverpage-image">
+        <a:documentation>Images to be displayed on the coverpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="innercoverpage-image">
+        <a:documentation>Images to be displayed on the inner coverpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="tocside-image">
+        <a:documentation>Images to be displayed on the Table of Contents page of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="backpage-image">
+        <a:documentation>Images to be displayed on the backpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+  </define>
   <define name="StandardBibliographicItem">
     <ref name="BibliographicItem"/>
     <zeroOrMore>