relaton 3.0.3 → 3.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a774b326943089257e3aef6e5402fc1e2d53d4ff557e8b19f845a62d64b9a99b
-  data.tar.gz: 665fa378d2380f79a4e2952df1ff3d0f7e1de6d91ead262d75261555a4170e5c
+  metadata.gz: 6e8ce7b77ba7b71f2bc7232319b926e70116ca3cdadf53395ef39e1dc4437a64
+  data.tar.gz: d0f29e54fa2129e444819703dfbd9b20ced132b34613053b6944b560370f9447
 SHA512:
-  metadata.gz: bfa2af357a4e288f0ce97fb82ff78ac58b39bc8f8fc8659584ebb29a4568a50175137b8b8cd32b6710aff65b8413cb4ab0d1ea674918187edd9a74592e331a6c
-  data.tar.gz: e2ad6a9822a6ffa5f9a625bb4095260b81b3906fcff8ba0cf4fbdcea0d543f9e2b14133c7dd29dad0f165c26713b16fc0f06ebfc06d134384d4d0f280ee873b1
+  metadata.gz: 158c8d47b5a66ddd647f568aa35327ec4f1ee51e5d4ece559c77a610d3ac9474bcd90aa9bcedd544dd0cdaacf7dcac74f72560f810e014c2caa86477d7e33954
+  data.tar.gz: bf49242892015cae4f95d8b63120aa494bb936db2dd98eac34ac8f90ca1f94b889f7d99fd79cc933777f5a04796cb48dc3b933a110f79e29ce6d1f283bb5b744

data/lib/relaton/3gpp/data_fetcher.rb

@@ -1,3 +1,4 @@
+require "yeptris/psych"
 require "fileutils"
 require "net/http"
 require "uri"
@@ -64,7 +65,7 @@ module Relaton
       # @return [String, nil] file name
       #
       def get_file(renewal) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        @current = YAML.load_file CURRENT if File.exist? CURRENT
+        @current = Yeptris::Psych.load_file CURRENT if File.exist? CURRENT
         @current ||= {}
         uri = URI(CSV_URL)
         n = 0
@@ -183,7 +184,7 @@ module Relaton
       # @return [Relaton3gpp::BibliographicItem, nil] merged bibliographic item or nil if no merge has been done
       #
       def merge_duplication(bib, file)
-        hash = YAML.load_file file
+        hash = Yeptris::Psych.load_file file
         existed = Item.from_hash hash
         changed = update_source? bib, existed
         bib1, bib2, chng = transposed_relation bib, existed

data/lib/relaton/bib/CLAUDE.md

@@ -61,7 +61,15 @@ Each bibliographic attribute has its own class in `lib/relaton/bib/model/`:
 **`Relaton::Bib::Sanitizer`** ([lib/relaton/bib/sanitizer.rb](lib/relaton/bib/sanitizer.rb))
 strips markup outside the basicdoc set. `LocalizedMarkedUpString#content=` calls it on
 assignment, so every `Title`, `Abstract`, `Note`, `Formattedref` and `Docidentifier` in
-every flavor passes through it. Two properties are load-bearing:
+every flavor passes through it. The set it keeps depends on the field, through
+`#sanitizer_allowed`: every field keeps `ALLOWED` (basicdoc inline markup), and `Abstract`
+keeps `ALLOWED_WITH_BLOCKS`, which adds `BLOCK` — the basicdoc lists, notes, tables, figures
+and admonitions, with the children their grammar requires (`name`, `thead`/`tbody`/`tfoot`,
+`image`). That split follows `biblio.rng`: `<abstract>` takes `BasicBlockNoId`, and a title,
+note, docidentifier or formattedref takes only `PureTextElement`, so do not widen the
+default. Before relaton#421 an abstract's list or note unwrapped to bare `<p>`s with no
+error. A consumer must therefore not assume that an abstract holds only `<p>` and inline
+markup. Two properties are load-bearing:
 
 - **It does not give up on an undeclared namespace prefix.** Third-party markup prefixes
   its elements — Crossref returns JATS as `<jats:p><jats:italic>x</jats:italic></jats:p>`,
@@ -99,7 +107,17 @@ every flavor passes through it. Two properties are load-bearing:
 ### Rendering
 
 - **`Renderer::BibtexBuilder`** - Converts `ItemData` to BibTeX format
-- **`Converter::BibXml`** - Converts `ItemData` to RFC XML format via `Relaton::Bib::Converter::BibXml.to_xml`
+- **`Converter::BibXml`** - Converts `ItemData` to an `Rfcxml::V3` model object via
+  `Relaton::Bib::Converter::BibXml.from_item`; call `to_xml` on the result (this is what
+  `ItemData#to_rfcxml` does). Two output shapes share one class hierarchy:
+  - `ToRfcxml` / `ToRfcxmlReferencegroup` (default) emit **BibXML**, the shape the Relaton
+    data repositories publish. It keeps the RFC 7991-deprecated `<format>` element, so it
+    must stay byte-compatible — every relaton data fetcher's `"bibxml"` format is
+    `entry.to_rfcxml`. Do not change its output.
+  - `ToRfcxmlV3` / `ToRfcxmlReferencegroupV3` (`v3: true`) subclass those and emit strict
+    **RFC 7991**: no `<format>`, plus `<stream>`, `ascii*` attributes and `<refcontent>`.
+    New v3-only behaviour belongs in the subclass, so the default path stays untouched by
+    construction and `spec/bib/relaton/bib/converter/bibxml_spec.rb` keeps passing unedited.
 - **lutaml-model native** - `to_xml`, `to_yaml`, `to_json` via the serialization classes
 
 ### Usage Pattern
@@ -120,11 +138,13 @@ item.to_xml                    # as <bibitem>
 item.to_xml(bibdata: true)     # as <bibdata>
 item.to_yaml
 item.to_bibtex
-item.to_rfcxml
+item.to_rfcxml                 # BibXML (what the data repos publish)
+item.to_rfcxml(v3: true)       # strict RFC 7991 / xml2rfc v3
+item.to_rfcxml(anchor: "ISO712", include_keywords: false)
 ```
 
 ## Code Style
 
 - Follows Ribose OSS Ruby style guide (inherited via `.rubocop.yml`)
-- Target Ruby version: 3.1+
+- Target Ruby version: 3.3+ (`required_ruby_version` in the gemspec, `TargetRubyVersion` in `.rubocop.yml`)
 - Uses YARD documentation comments

data/lib/relaton/bib/README.adoc

@@ -311,6 +311,70 @@ item.to_rfcxml
 </reference>
 ----
 
+=== Export bibliographic item to strict RFC XML v3
+
+`to_rfcxml` emits the BibXML shape published by the Relaton data repositories,
+which still carries the `<format>` element that RFC 7991 deprecates. Pass
+`v3: true` for output that follows the RFC 7991 (xml2rfc v3) vocabulary
+instead: no `<format>`, a `<stream>` element, `ascii*` attributes, and
+`<refcontent>` for identifiers that cannot be expressed as `<seriesInfo>`.
+
+[source,ruby]
+----
+item.to_rfcxml v3: true
+<reference anchor="ISO20483">
+  <front>
+    <title>Cereals and pulses</title>
+    <author initials="Ö." asciiInitials="O." surname="Nürk" asciiSurname="Nurk"/>
+    <author>
+      <organization abbrev="ISO" ascii="International Organization for Standardization">International Organization for Standardization</organization>
+    </author>
+    <date year="2013"/>
+  </front>
+  <refcontent>ISO 20483:2013-2014</refcontent>
+</reference>
+----
+
+Documents published by the IETF (identified by a contributing organization
+named `IETF`, `Internet Engineering Task Force` or `RFC Publisher`) express
+their identifiers as `<seriesInfo>` rather than `<refcontent>`:
+
+[source,ruby]
+----
+<reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
+  <stream>IETF</stream>
+  <front>
+    <title>Key words for use in RFCs to Indicate Requirement Levels</title>
+    <seriesInfo name="BCP" value="14"/>
+    <seriesInfo name="RFC" value="2119"/>
+    ...
+  </front>
+</reference>
+----
+
+The v3 mode also applies the citation rules the IETF toolchain expects, which
+the BibXML mode leaves alone:
+
+* Contributors with role `author` or `editor` become `<author>`; the wider set
+  (`publisher`, `authorizer`, `translator`, …) is used only when the item names
+  no author or editor, so an RFC's publisher is not listed as its author.
+* `<title>` takes the composite `title[@type="main"]`, else joins
+  title-intro / title-main / title-part, so multipart standards keep their full
+  title. Inline markup is flattened, since v3 `<title>` is text-only.
+* Identifiers that restate the reference label, `URN` identifiers and the
+  `I-D.` anchor form are left out of `<refcontent>`; Internet-Draft
+  `<seriesInfo>` carries the full `draft-…` name, which is what xml2rfc
+  resolves against.
+* Where folding a name leaves no letters (a non-Latin script), the `ascii*`
+  attribute is omitted rather than emitted blank.
+
+Two further options are accepted by both modes:
+
+`anchor:`:: overrides the anchor otherwise derived from `docnumber`, for
+callers that carry their own identifier (for example a Metanorma Semantic XML
+`bibitem/@id`).
+`include_keywords:`:: set to `false` to suppress `<keyword>` elements.
+
 === Logging
 
 RelatonBib uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.

data/lib/relaton/bib/converter/bibxml/from_rfcxml.rb

@@ -326,7 +326,18 @@ module Relaton
 
               t = Title.new(content: si.name, language: "en", script: "Latn")
               Series.new(title: [t], number: si.value, type: "main")
-            end.compact
+            end.compact + stream_series
+          end
+
+          # RFC XML v3 carries the publication stream in a <stream> element.
+          # ItemData has no dedicated slot for it, so it is kept the way
+          # relaton-ietf does: as a series marked `type="stream"`.
+          def stream_series
+            return [] unless @reference.stream
+
+            t = Title.new(content: @reference.stream, language: "en",
+                          script: "Latn")
+            [Series.new(title: [t], type: "stream")]
           end
 
           # --- Keyword ---

data/lib/relaton/bib/converter/bibxml/to_rfcxml.rb

@@ -5,14 +5,15 @@ module Relaton
     module Converter
       module BibXml
         class ToRfcxml
-          def initialize(item, include_keywords: true)
+          def initialize(item, include_keywords: true, anchor: nil)
             @item = item
             @include_keywords = include_keywords
+            @anchor = anchor
           end
 
           def transform
             model = ::Rfcxml::V3::Reference.new
-            model.anchor = @item.docnumber || derive_anchor
+            model.anchor = @anchor || @item.docnumber || derive_anchor
             model.target = create_target
             model.front = create_front
             model.format = create_format
@@ -26,14 +27,22 @@ module Relaton
             di&.content&.to_s&.gsub(" ", ".")
           end
 
+          # A <uri> may legitimately carry no type -- biblio.rng makes it
+          # optional, and hand-authored bibitems often omit it -- so never call
+          # String methods on it unguarded.
+          def target_types = %w[src doi]
+
           def create_target
-            target = @item.source.detect { |l| l.type.casecmp("src").zero? } ||
-              @item.source.detect { |l| l.type.casecmp("doi").zero? }
+            target = target_types.filter_map { |t| source_of_type(t) }.first
             return unless target
 
             target.content.to_s
           end
 
+          def source_of_type(type)
+            @item.source.detect { |l| l.type&.casecmp(type)&.zero? }
+          end
+
           def create_front # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
             front = ::Rfcxml::V3::Front.new
             front.title = Rfcxml::V3::Title.new(content: @item.title[0].content) if @item.title.any?
@@ -59,9 +68,16 @@ module Relaton
             end
           end
 
+          # A `type="stream"` series is the publication stream, not a series:
+          # it has no number, so it would yield a valueless <seriesInfo>.
+          def seriesinfo_series?(ser)
+            ser.type != "stream" &&
+              ser.title.reject { |t| t.content == "DOI" }.any?
+          end
+
           def series_to_seriesinfo # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
             @item.series.select do |s|
-              s.title.reject { |t| t.content == "DOI" }.any?
+              seriesinfo_series?(s)
             end.uniq do |s|
               s.title.find { |t| t.content != "DOI" }.content
             end.each_with_object([]) do |s, si|
@@ -71,8 +87,13 @@ module Relaton
             end
           end
 
+          # Which contributors become <author>; overridden by the v3 emitter.
+          def contributors_for_authors
+            @item.contributor.reject { |c| committee_contributor?(c) }
+          end
+
           def create_authors # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-            @item.contributor.reject { |c| committee_contributor?(c) }.map do |contrib|
+            contributors_for_authors.map do |contrib|
               role = "editor" if contrib.role.detect { |r| r.type == "editor" }
               Rfcxml::V3::Author.new(
                 role: role,
@@ -284,7 +305,10 @@ module Relaton
             return unless @item.abstract.any?
 
             content = @item.abstract[0].content
-            paragraphs = content.scan(%r{<p>(.*?)</p>}m).flatten
+            # Semantic XML paragraphs carry attributes (`<p id="_349ea…">`);
+            # match those too, or the whole abstract falls through to the
+            # fallback below and the markup is escaped into the <t>.
+            paragraphs = content.scan(%r{<p\b[^>]*>(.*?)</p>}m).flatten
             paragraphs = [content] if paragraphs.empty?
             ts = paragraphs.map { |p| Rfcxml::V3::Text.new(content: CGI.unescapeHTML(p)) }
             Rfcxml::V3::Abstract.new(t: ts)
@@ -294,7 +318,7 @@ module Relaton
 
           def create_format # rubocop:disable Metrics/AbcSize
             @item.source.each_with_object([]) do |l, a|
-              next unless FORMAT_TYPES.any? { |ft| l.type.casecmp(ft).zero? }
+              next unless FORMAT_TYPES.any? { |ft| l.type&.casecmp(ft)&.zero? }
 
               a << Rfcxml::V3::Format.new(
                 type: l.type, target: l.content,

data/lib/relaton/bib/converter/bibxml/to_rfcxml_referencegroup.rb

@@ -3,9 +3,10 @@ module Relaton
     module Converter
       module BibXml
         class ToRfcxmlReferencegroup
-          def initialize(item, include_keywords: true)
+          def initialize(item, include_keywords: true, anchor: nil)
             @item = item
             @include_keywords = include_keywords
+            @anchor = anchor
           end
 
           def transform
@@ -30,6 +31,8 @@ module Relaton
           end
 
           def create_anchor
+            return @anchor if @anchor
+
             docid = @item.docidentifier.detect(&:primary) ||
               @item.docidentifier[0]
             return unless docid
@@ -38,9 +41,13 @@ module Relaton
             id.sub(/^(RFC|BCP|FYI|STD) /, '\1').sub(/^\w+\./, "")
           end
 
+          # An untyped <uri> is legal, so guard before comparing.
+          def target_types = %w[src doi]
+
           def create_target
-            target = @item.source.detect { |l| l.type.casecmp("src").zero? } ||
-              @item.source.detect { |l| l.type.casecmp("doi").zero? }
+            target = target_types.filter_map do |type|
+              @item.source.detect { |l| l.type&.casecmp(type)&.zero? }
+            end.first
             return unless target
 
             target.content.to_s

data/lib/relaton/bib/converter/bibxml/to_rfcxml_referencegroup_v3.rb

@@ -0,0 +1,43 @@
+module Relaton
+  module Bib
+    module Converter
+      module BibXml
+        #
+        # Strict RFC 7991 flavour of {ToRfcxmlReferencegroup}: members are
+        # rendered by {ToRfcxmlV3}, and every one of them gets an anchor,
+        # which the v3 grammar makes mandatory on `<reference>`.
+        #
+        class ToRfcxmlReferencegroupV3 < ToRfcxmlReferencegroup
+          private
+
+          def target_types = %w[src HTML doi]
+
+          # <referencegroup> needs an anchor just as much as its members do,
+          # so fall back past the docidentifier the parent relies on.
+          def create_anchor
+            anchor = super || @item.docnumber || @item.id
+            anchor && anchor.to_s.strip.gsub(/\s+/, ".")
+          end
+
+          def build_references
+            included_items.each_with_index.map do |item, idx|
+              ref = ToRfcxmlV3.new(item, include_keywords: @include_keywords)
+                .transform
+              ref.anchor = member_anchor(idx) if ref.anchor.to_s.empty?
+              ref
+            end
+          end
+
+          def included_items
+            @item.relation.select { |rel| rel.type == "includes" }
+              .map(&:bibitem)
+          end
+
+          def member_anchor(idx)
+            "#{create_anchor || 'reference'}_#{idx + 1}"
+          end
+        end
+      end
+    end
+  end
+end