relaton-bib 0.4.1 → 0.5.0

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/docs/hash.adoc

@@ -4,9 +4,26 @@
 
 The following structure is in place for encoding bibitem as YAML objects, and is also used 
 to represent bibliographic entries in Metanorma Asciidoctor. The structure has not yet been
-generalised to `bibdata/ext`, the flavour specific extensions of relaton.
+generalised to `bibdata/ext`, the flavour-specific extensions of relaton.
 
-Any elements which are arrays can also be populated by a hash or single element. For example,
+If an element in Relaton XML has attributes, the content of the element is represented in YAML
+with a `content` key:
+
+[source,xml]
+....
+<title type="main">Geographic information</title>
+....
+
+[source,yaml]
+....
+title:
+  type: main
+  content: Geographic information
+....
+
+Any elements with a cardinality of many can be represented as arrays, but
+they can also be populated by a hash or single element. For example,
+a Relaton title can have multiple titles, and multiple scripts; so
 the following are equivalent:
 
 [source,yaml]
@@ -254,22 +271,53 @@ validity:
   revision: 2011-03-04 09:00
 ....
 
-== Metanorma structure: nested definition list
+== Metanorma structure (AsciiBib): nested definition list
 
-The Metanorma Asciidoctor representation of this hash structure
+The Metanorma Asciidoctor representation of the Relaton hash structure
 in a bibliography
-is as a definition list, with nested definition lists for nested structures.
+is as a definition list of element name and element contents,
+with nested definition lists for nested structures. If a nested
+definition is given for an element, the element itself has a blank definition.
+
+As with the YAML representation, if an element in Relaton XML has attributes, 
+the content of the element is represented in YAML with a `content` key:
+
+[source,xml]
+....
+<title type="main">Geographic information</title>
+....
+
+[source,asciidoc]
+....
+title::
+  type::: main
+  content::: Geographic information
+....
+
+Likewise, as with the YAML representation,
 Repeating elements in a hash can be realised as ordered or unordered lists.
-However, given how awkward lists of definition lists are in Asciidoctor
-(with a limitation of three nesting levels),
-Metanorma Asciidoctor also supports representing repeating elements 
-by repeating the key for that entry.
+
+[source,asciidoc]
+----
+language::
+  . en
+  . fr
+----
+
+Metanorma Asciidoctor also supports representing repeating elements
+by repeating the key for that entry. This will almost always be more
+straightforward to use in Asciidoctor:
+
+[source,asciidoc]
+----
+language:: en
+language:: fr
+----
 
 Each Relaton entry in a bibliography is represented in Metanorma Asciidoctor
 through a subclause with option attribute `[%bibitem]`. Any title given to the
 subclause is treated as the title for the bibliographic entry, with language `en`,
-script `Latn`, format `text/plain`, and type `main`. If there is no such title
-for the entry, the subclause title should be left as `{blank}`.
+script `Latn`, format `text/plain`, and type `main`. 
 
 So the following is a very simple reference in Metanorma Asciidoctor:
 
@@ -287,9 +335,28 @@ docid::
 type:: standard
 ----
 
-The anchor crossreference for the bibliographic entry may be encoded as the
+If there is no such title
+for the entry, the subclause title should be left as `{blank}`, and the desired
+title should be given in the hash body:
+
+[source,asciidoc]
+----
+[%bibitem]
+=== {blank}
+id:: iso123
+title::
+language::: fr
+script::: Latn
+format::: text/plain
+type::: alt
+content::: Latex de caoutchouc -- Échantillonnage
+----
+
+Note the use of `content` as a key to represent the contents of the `title` tag.
+
+The anchor crossreference for the bibliographic entry may be encoded as either the
 `id` entry in the definition list, or as the normal Asciidoctor anchor on the
-subclause, which takes priority over it:
+subclause, which takes priority:
 
 [source,asciidoc]
 ----
@@ -302,9 +369,40 @@ docid::
 type:: standard
 ----
 
-Asciidoctor does not currently cope with definition lists more than four levels
+Repeating elements in a hash can be realised as ordered or unordered lists.
+
+[source,asciidoc]
+----
+[[iso123]]
+[%bibitem]
+=== Rubber latex -- Sampling
+docid:: 
+  type::: ISO
+  id::: ISO 123
+language::
+  . en
+  . fr
+----
+
+Metanorma Asciidoctor also supports representing repeating elements  
+by repeating the key for that entry. This will almost always be more
+straightforward to use in Asciidoctor:
+
+[source,asciidoc]
+----
+[[iso123]]
+[%bibitem]
+=== Rubber latex -- Sampling
+docid:: 
+  type::: ISO
+  id::: ISO 123
+language:: en
+language:: fr
+----
+
+Asciidoctor does not recognise definition lists more than four levels
 deep. If deeper nesting is needed, you will need to attach a new definition
-list with a list continuation:
+list with a list continuation, with the definition list depth reset back to one:
 
 [source,asciidoc]
 ----
@@ -327,13 +425,22 @@ completename::
 --
 ----
 
+(This is very awkward, and <<JSONPath>> provides a workaround.)
+
 The most heavily nested parts of a Relaton entry are the contributors,
-series, and relations. To prevent excessive depth of nesting for such
-entries, they can be marked up as subclauses within the entry, with the clause
+series, and relations. 
+Each of these can be marked up as subclauses within the entry, with the clause
 titles "contributor", "series", and "relation". Each subclause contains
 a new definition list, with its definition list reset to zero depth;
 the subclauses can be repeated for multiple instances of the same subentity.
 
+AsciiBib citations can be combined with other Asciidoctor citations in the
+same Metanorma document; but any Asciidoctor citations need be precede
+AsciiBib citations. Each AsciiBib citations constitutes a subclause of its own,
+and Metanorma will (unsuccessfully) attempt to incorporate any trailing material
+in the subclause, including  Asciidoctor citations, into the current AsciiBib
+citation.
+
 The following is Metanorma Asciidoctor markup corresponding to the YAML
 given above:
 
@@ -549,11 +656,14 @@ formattedref::
   script::: Latn
 ....
 
+[[JSONPath]]
 == JSON Path style definition lists
 
 The foregoing structure requires frequent breakouts into open blocks, to deal
 with the limitation on Asciidoctor nested definition lists. An alternative is to
-represent the nested structure of Relaton records in a simple, one-level definition list, and to use the key for each key-value pair to represent the hierarchical nesting of entries, as a dot-delimited path of keys. For example,
+represent the nested structure of Relaton records in a simple, one-level definition list, 
+and to use the key for each key-value pair to represent the hierarchical nesting of entries, 
+as a dot-delimited path of keys. For example,
 
 [source,asciidoc]
 ----
@@ -573,7 +683,7 @@ can instead be represented as:
 === Rubber latex -- Sampling
 id:: iso123
 docid.type:: ISO
-docid.id::: ISO 123
+docid.id:: ISO 123
 ----
 
 Whenever part of the key is repeated between entries, the entries are assumed to attach to the same parent. If an array of hashes is needed, a blank entry is required for the key of each repeating element: For example,
@@ -601,7 +711,7 @@ can instead be represented as:
 id:: iso123
 docid::
 docid.type:: ISO
-docid.id::: ISO 123
+docid.id:: ISO 123
 docid::
 docid.type:: ABC
 docid.id:: 32784

data/lib/relaton_bib/bibliographic_item.rb

@@ -18,10 +18,12 @@ require "relaton_bib/validity"
 require "relaton_bib/document_relation"
 require "relaton_bib/bib_item_locality"
 require "relaton_bib/xml_parser"
+require "relaton_bib/bibtex_parser"
 require "relaton_bib/biblio_note"
 require "relaton_bib/biblio_version"
 require "relaton_bib/workers_pool"
 require "relaton_bib/hash_converter"
+require "relaton_bib/place"
 
 module RelatonBib
   # Bibliographic item
@@ -93,7 +95,7 @@ module RelatonBib
     # @return [RelatonBib::Medium, NilClass]
     attr_reader :medium
 
-    # @return [Array<String>]
+    # @return [Array<RelatonBib::Place>]
     attr_reader :place
 
     # @return [Array<RelatonBib::BibItemLocality>]
@@ -102,7 +104,7 @@ module RelatonBib
     # @return [Array<Strig>]
     attr_reader :accesslocation
 
-    # @return [Relaton::Classification, NilClass]
+    # @return [Array<Relaton::Classification>]
     attr_reader :classification
 
     # @return [RelatonBib:Validity, NilClass]
@@ -128,10 +130,10 @@ module RelatonBib
     # @param biblionote [Array<RelatonBib::BiblioNote>]
     # @param series [Array<RelatonBib::Series>]
     # @param medium [RelatonBib::Medium, NilClas]
-    # @param place [Array<String>]
+    # @param place [Array<String, RelatonBib::Place>]
     # @param extent [Array<Relaton::BibItemLocality>]
     # @param accesslocation [Array<String>]
-    # @param classification [RelatonBib::Classification, NilClass]
+    # @param classification [Array<RelatonBib::Classification>]
     # @param validity [RelatonBib:Validity, NilClass]
     # @param fetched [Date, NilClass] default nil
     #
@@ -214,10 +216,10 @@ module RelatonBib
       @link           = args.fetch(:link, []).map { |s| s.is_a?(Hash) ? TypedUri.new(s) : s }
       @series         = args.fetch :series, []
       @medium         = args[:medium]
-      @place          = args.fetch(:place, [])
+      @place          = args.fetch(:place, []).map { |pl| pl.is_a?(String) ? Place.new(name: pl) : pl }
       @extent         = args[:extent] || []
       @accesslocation = args.fetch :accesslocation, []
-      @classification = args[:classification]
+      @classification = args.fetch :classification, []
       @validity       = args[:validity]
       @fetched        = args.fetch :fetched, nil # , Date.today # we should pass the fetched arg from scrappers
     end
@@ -298,12 +300,37 @@ module RelatonBib
       hash["place"] = single_element_array(place) if place&.any?
       hash["extent"] = single_element_array(extent) if extent&.any?
       hash["accesslocation"] = single_element_array(accesslocation) if accesslocation&.any?
-      hash["classification"] = classification.to_hash if classification
+      hash["classification"] = single_element_array(classification) if classification&.any?
       hash["validity"] = validity.to_hash if validity
       hash["fetched"] = fetched.to_s if fetched
       hash
     end
 
+    # @param bibtex [BibTeX::Bibliography, NilClass]
+    # @return [String]
+    def to_bibtex(bibtex = nil)
+      item = BibTeX::Entry.new
+      item.type = bibtex_type
+      item.key = id
+      bibtex_title item
+      item.edition = edition if edition
+      bibtex_author item
+      bibtex_contributor item
+      item.address = place.first.name if place.any?
+      bibtex_note item
+      bibtex_relation item
+      bibtex_extent item
+      bibtex_date item
+      bibtex_series item
+      bibtex_classification item
+      bibtex_docidentifier item
+      item.timestamp = fetched.to_s if fetched
+      bibtex_link item
+      bibtex ||= BibTeX::Bibliography.new
+      bibtex << item
+      bibtex.to_s
+    end
+
     # If revision_date exists then returns it else returns published date or nil
     # @return [String, NilClass]
     def revdate
@@ -316,6 +343,146 @@ module RelatonBib
 
     private
 
+    # @return [String]
+    def bibtex_title(item)
+      title.each do |t|
+        case t.type
+        when "main" then item.tile = t.title.content
+        end
+      end
+    end
+
+    # @return [String]
+    def bibtex_type
+      case type
+      when "standard", nil then "misc"
+      else type
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_author(item)
+      authors = contributor.select do |c|
+        c.entity.is_a?(Person) && c.role.map(&:type).include?("author")
+      end.map &:entity
+
+      return unless authors.any?
+
+      item.author = authors.map do |a|
+        if a.name.surname
+          "#{a.name.surname}, #{a.name.forename.map(&:to_s).join(" ")}"
+        else
+          a.name.completename.to_s
+        end
+      end.join " and "
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_contributor(item)
+      contributor.each do |c|
+        rls = c.role.map(&:type)
+        if rls.include?("publisher") then item.publisher = c.entity.name
+        elsif rls.include?("distributor")
+          case type
+          when "techreport" then item.institution = c.entity.name
+          when "inproceedings", "conference", "manual", "proceedings"
+            item.organization = c.entity.name
+          when "mastersthesis", "phdthesis" then item.school = c.entity.name
+          end
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_note(item)
+      biblionote.each do |n|
+        case n.type
+        when "annote" then item.annote = n.content
+        when "howpublished" then item.howpublished = n.content
+        when "comment" then item.comment = n.content
+        when "tableOfContents" then item.content = n.content
+        when nil then item.note = n.content
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_relation(item)
+      rel = relation.detect { |r| r.type == "partOf" }
+      item.booktitle = rel.bibitem.title.detect { |t| t.type == "main" }.title.content if rel
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_extent(item)
+      extent.each do |e|
+        case e.type
+        when "chapter" then item.chapter = e.reference_from
+        when "page"
+          value = e.reference_from
+          value += "-#{e.reference_to}" if e.reference_to
+          item.pages = value
+        when "volume" then item.volume = e.reference_from
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_date(item)
+      date.each do |d|
+        case d.type
+        when "published"
+          item.year = d.on.year
+          item.month = d.on.month
+        when "accessed" then item.urldate = d.on.to_s
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_series(item)
+      series.each do |s|
+        case s.type
+        when "journal"
+          item.journal = s.title.title
+          item.number = s.number if s.number
+        when nil then item.series = s.title.title
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_classification(item)
+      classification.each do |c|
+        case c.type
+        when "type" then item["type"] = c.value
+        when "keyword" then item.keywords = c.value
+        when "mendeley" then item["mendeley-tags"] = c.value
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_docidentifier(item)
+      docidentifier.each do |i|
+        case i.type
+        when "isbn" then item.isbn = i.id
+        when "lccn" then item.lccn = i.id
+        when "issn" then item.issn = i.id
+        end
+      end
+    end
+
+    # @param [BibTeX::Entry]
+    def bibtex_link(item)
+      link.each do |l|
+        case l.type
+        when "doi" then item.doi = l.content
+        when "file" then item.file2 = l.content
+        when "src" then item.url = l.content
+        end
+      end
+    end
+
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     # rubocop:disable Style/NestedParenthesizedCalls, Metrics/BlockLength
@@ -349,10 +516,10 @@ module RelatonBib
         relation.each { |r| r.to_xml builder, **opts }
         series.each { |s| s.to_xml builder }
         medium&.to_xml builder
-        place.each { |pl| builder.place pl }
+        place.each { |pl| pl.to_xml builder }
         extent.each { |e| builder.extent { e.to_xml builder } }
         accesslocation.each { |al| builder.accesslocation al }
-        classification&.to_xml builder
+        classification.each { |cls| cls.to_xml builder }
         validity&.to_xml builder
         if block_given?
           yield builder