= RelatonIsoBib

image:https://img.shields.io/gem/v/relaton-iso-bib.svg["Gem Version", link="https://rubygems.org/gems/relaton-iso-bib"]
image:https://img.shields.io/travis/metanorma/relaton-iso-bib/master.svg["Build Status", link="https://travis-ci.com/metanorma/relaton-iso-bib"]
image:https://codeclimate.com/github/metanorma/relaton-iso-bib/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/relaton-iso-bib"]

IsoBib is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].

== Installation

Add this line to your application's Gemfile:

[source,ruby]
----
gem 'relaton-iso-bib'
----

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install relaton-iso-bib

== Usage

=== Create ISO bibliographic item

[source,ruby]
----
item = RelatonIsoBib::IsoBibliographicItem.new(
    fetched: "2018-10-21",
    structuredidentifier: RelatonIsoBib::StructuredIdentifier.new(
      type: "sid", project_number: "ISO 1-2:2014", part: 2, subpart: 2,
    ),
    docnumber: "123456",
    title: [
      { title_intro: "Geographic information", title_main: "Metadata",
        title_part: "Part 1: Fundamentals", language: "en", script: "Latn" },
      { title_intro: "Information géographique", title_main: "Métadonnées",
        title_part: "Information géographique", language: "fr",
        script: "Latn" },
    ],
    edition: "1",
    version: RelatonBib::BibliographicItem::Version.new("2019-04-01", ["draft"]),
    language: %w[en fr],
    script: ["Latn"],
    type: "international-standard",
    docstatus: RelatonBib::DocumentStatus.new(stage: "60", substage: "60"),
    dates: [{ type: "published", on: "2014-04" }],
    abstract: [
      { content: "ISO 19115-1:2014 defines the schema required for ...",
        language: "en", script: "Latn", format: "text/plain" },
      { content: "L'ISO 19115-1:2014 définit le schéma requis pour ...",
        language: "fr", script: "Latn", format: "text/plain" },
    ],
    contributor: [
      { entity: { name: "International Organization for Standardization",
                  url: "www.iso.org", abbreviation: "ISO" },
        role: ["publisher"] },
      {
        entity: RelatonBib::Person.new(
          name: RelatonBib::FullName.new(
            completename: RelatonBib::LocalizedString.new("John Smith"),
          ),
        ),
        role: ["author"],
      },
    ],
    copyright: { owner: {
      name: "International Organization for Standardization",
      abbreviation: "ISO", url: "www.iso.org"
    }, from: "2014" },
    link: [
      { type: "src", content: "https://www.iso.org/standard/53798.html" },
      { type: "obp",
        content: "https://www.iso.org/obp/ui/#!iso:std:53798:en" },
      { type: "rss", content: "https://www.iso.org/contents/data/standard"\
        "/05/37/53798.detail.rss" },
    ],
    relation: [
      RelatonBib::DocumentRelation.new(
        type: "updates",
        bibitem: RelatonIsoBib::IsoBibliographicItem.new(
          formattedref: RelatonBib::FormattedRef.new(content: "ISO 19115:2003"),
          docstatus: RelatonBib::DocumentStatus.new(stage: "60", substage: "60"),
        ),
        bib_locality: [
          RelatonBib::BibItemLocality.new("updates", "Reference form"),
        ],
      ),
      RelatonBib::DocumentRelation.new(
        type: "updates",
        bibitem: RelatonIsoBib::IsoBibliographicItem.new(
          type: "international-standard",
          formattedref: RelatonBib::FormattedRef.new(content: "ISO 19115:2003/Cor 1:2006"),
        ),
      ),
    ],
    series: [
      RelatonBib::Series.new(
        type: "main",
        title: RelatonIsoBib::TypedTitleString.new(
          type: "title-main", content: "ISO/IEC FDIS 10118-3", language: "en", script: "Latn",
        ),
        place: "Serie's place",
        organization: "Serie's organization",
        abbreviation: RelatonBib::LocalizedString.new("ABVR", "en", "Latn"),
        from: "2009-02-01",
        to: "2010-12-20",
        number: "serie1234",
        partnumber: "part5678",
      ),
      RelatonBib::Series.new(
        type: "alt",
        formattedref: RelatonBib::FormattedRef.new(
          content: "serieref", language: "en", script: "Latn",
        ),
      )
    ],
    medium: RelatonBib::Medium.new(
      form: "medium form", size: "medium size", scale: "medium scale",
    ),
    place: ["bib place"],
    extent: [
      RelatonBib::BibItemLocality.new(
        "section", "Reference from", "Reference to"
      ),
    ],
    accesslocation: ["accesslocation1", "accesslocation2"],
    classification: RelatonBib::Classification.new(type: "type", value: "value"),
    validity: RelatonBib::Validity.new(
      begins: Time.new(2010, 10, 10, 12, 21),
      ends: Time.new(2011, 2, 3, 18,30),
      revision: Time.new(2011, 3, 4, 9, 0),
    ),
    editorialgroup: {
      technical_committee: [{
        name: " ISO/TC 211 Geographic information/Geomatics",
        type: "technicalCommittee", number: 211
      }],
      subcommittee: [{
        name: "International Organization for Standardization",
        type: "ISO", number: 122,
      }],
      workgroup: [RelatonIsoBib::IsoSubgroup.new(
        name: "Workgroup Organization",
        type: "WG", number: 111,
      )],
    },
    ics: [{ field: 35, group: 240, subgroup: 70 }],
  )

=> #<RelatonIsoBib::IsoBibliographicItem:0x007fe5198c4370
 @abstract=
  [#<RelatonBib::FormattedString:0x007fe5198bcaa8 @content="ISO 19115-1:2014 defines the schema required for ...", @format="text/plain", @language=["en"], @script=["Latn"]>,
  ...
----

=== IsoBibliographicItem Localized Strings

[source,ruby]
----
item.title
=> [#<RelatonIsoBib::TypedTitleString:0x007fe5198ad4e0
  @title=#<RelatonBib::FormattedString:0x007fe5198acd10 @content="Metadata", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198ac590
  @title=#<RelatonBib::FormattedString:0x007fe5198a7ab8 @content="Geographic information", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198a6f00
  @title=#<RelatonBib::FormattedString:0x007fe5198a6578 @content="Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198a5d08
  @title=
   #<RelatonBib::FormattedString:0x007fe5198a5268 @content="Metadata - Geographic information - Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198a4980
  @title=#<RelatonBib::FormattedString:0x007fe51989edf0 @content="Métadonnées", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51989d1a8
  @title=#<RelatonBib::FormattedString:0x007fe51989cca8 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51989c960
  @title=#<RelatonBib::FormattedString:0x007fe519897d20 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonIsoBib::TypedTitleString:0x007fe519896088
  @title=
   #<RelatonBib::FormattedString:0x007fe519895b88
    @content="Métadonnées - Information géographique - Information géographique",
    @format="text/plain",
    @language=["fr"],
    @script=["Latn"]>,
  @type="main">]

item.title(lang: "en")
=> [#<RelatonIsoBib::TypedTitleString:0x007fe5198ad4e0
  @title=#<RelatonBib::FormattedString:0x007fe5198acd10 @content="Metadata", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198ac590
  @title=#<RelatonBib::FormattedString:0x007fe5198a7ab8 @content="Geographic information", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198a6f00
  @title=#<RelatonBib::FormattedString:0x007fe5198a6578 @content="Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198a5d08
  @title=
   #<RelatonBib::FormattedString:0x007fe5198a5268 @content="Metadata - Geographic information - Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="main">]

item.abstract(lang: "en").to_s
=> "ISO 19115-1:2014 defines the schema required for ..."
----

=== IsoBibliographicItem references

[source,ruby]
----
item.shortref(item.structuredidentifier)
=> "ISO1-2-2014:2014"
----

=== IsoBibliographicItem URLs

[source,ruby]
----
item.url
=> "https://www.iso.org/standard/53798.html"

item.url(:obp)
=> "https://www.iso.org/obp/ui/#!iso:std:53798:en"

item.url(:rss)
=> "https://www.iso.org/contents/data/standard/05/37/53798.detail.rss"
----


=== IsoBibliographicItem ICS

[source,ruby]
----
item.ics
[<RelatonIsoBib::Ics:0x007fd1d92334f0
  @code="35.240.70",
  @description="IT applications in science",
  @description_full="Information technology. Applications of information technology. IT applications in science.",
  @fieldcode="35",
  @groupcode="240",
  @notes=[#<Isoics::Note:0x007fd1d9232f28 @ics_code=nil, @text="Including digital geographic information">],
  @subgroupcode="70">]
----

=== IsoBibliographicItem BibliographicDates

[source,ruby]
----
item.dates
=> [<RelatonIsoBib::BibliographicDate:0x007fd1d92e33c8 @on=2014-01-04 00:00:00 +0100, @type="published">]

item.dates.filter(type: "published").first.on
=> 2014-01-04 00:00:00 +0100
----

=== IsoBibliographicItem DocumentStatus

[source,ruby]
----
item.status
=> #<RelatonBib::DocumentStatus:0x007fe5198d7808 @iteration=nil, @stage="60", @substage="60">
----

[source,ruby]
----
wg = item.editorialgroup
=> #<RelatonIsoBib::EditorialGroup:0x007fe519895200
 @secretariat=nil,
 @subcommittee=[#<RelatonIsoBib::IsoSubgroup:0x007fe519894a58 @name="International Organization for Standardization", @number=122, @type="ISO">],
 @technical_committee=[#<RelatonIsoBib::IsoSubgroup:0x007fe519894d78 @name=" ISO/TC 211 Geographic information/Geomatics", @number=211, @type="technicalCommittee">],
 @workgroup=[#<RelatonIsoBib::IsoSubgroup:0x007fe5198c4668 @name="Workgroup Organization", @number=111, @type="WG">]>
----

=== Document relations of a standard

[source,ruby]
----
item.relation
=> [#<RelatonBib::DocumentRelation:0x007fe5198cec80
  @bib_locality=[#<RelatonBib::BibItemLocality:0x007fe5198cef78 @reference_from="Reference form", @reference_to=nil, @type="updates">],
  @bibitem=
   #<RelatonIsoBib::IsoBibliographicItem:0x007fe5198d4ae0
  ...
----

=== Reference modification: convert to all parts reference

In ISO, an All Parts reference is a reference to all parts of a standard. If a standard consists of parts,
only those parts are referenced in the ISO web site (as retrieved by the isobib gem). A part reference is
converted to an All Parts reference by making the part reference a partOf relation to a new reference,
which strips the part number and part title of the original, and its abstract. The operation is destructive.

[source,ruby]
----
item.to_all_parts
=> true

item.title(lang: "en")
=> [#<RelatonIsoBib::TypedTitleString:0x007fe5198ad4e0
  @title=#<RelatonBib::FormattedString:0x007fe5198acd10 @content="Metadata", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198ac590
  @title=#<RelatonBib::FormattedString:0x007fe5198a7ab8 @content="Geographic information", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonIsoBib::TypedTitleString:0x007fe5198a5d08
  @title=
   #<RelatonBib::FormattedString:0x007fe5198a5268 @content="Metadata - Geographic information - Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="main">]

item.shortref(item.structuredidentifier)
=> "ISO1-2014(allparts):2014: All Parts"

item.relation.last.bibitem.title
=> [#<RelatonIsoBib::TypedTitleString:0x007fe51b293620
  @title=#<RelatonBib::FormattedString:0x007fe51b293530 @content="Metadata", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b293350
  @title=#<RelatonBib::FormattedString:0x007fe51b293288 @content="Geographic information", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b293120
  @title=#<RelatonBib::FormattedString:0x007fe51b293080 @content="Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b292f68
  @title=
   #<RelatonBib::FormattedString:0x007fe51b292ea0 @content="Metadata - Geographic information - Part 1: Fundamentals", @format="text/plain", @language=["en"], @script=["Latn"]>,
  @type="main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b292d60
  @title=#<RelatonBib::FormattedString:0x007fe51b292cc0 @content="Métadonnées", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-main">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b292b58
  @title=#<RelatonBib::FormattedString:0x007fe51b292ab8 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-intro">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b2929a0
  @title=#<RelatonBib::FormattedString:0x007fe51b292900 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
  @type="title-part">,
 #<RelatonIsoBib::TypedTitleString:0x007fe51b2927c0
  @title=
   #<RelatonBib::FormattedString:0x007fe51b292720
    @content="Métadonnées - Information géographique - Information géographique",
    @format="text/plain",
    @language=["fr"],
    @script=["Latn"]>,
  @type="main">]
----

=== Reference modification: convert to most recent reference

In ISO, an undated reference is interpreted as a _de dicto_ reference to the most recent instance of the
reference; if the document is read after a new version of the reference has been issued, the reference is taken
to refer to that new instance, even if that instance had not been published at the time the bibliography was authored.
All references on the ISO web site (as retrieved by the isobib gem) are dated. A dated reference is
converted to a Most Recent referece by making the dated reference an instance relation to a new reference,
which strips the date of publication of the original, and its abstract. The operation is destructive.

[source,ruby]
----
item.dates
=> [#<RelatonBib::BibliographicDate:0x007fe5198beba0 @from=nil, @on=2014-04-01 00:00:00 +0200, @to=nil, @type="published">]

item.to_most_recent_reference
item.dates
=> []

item.shortref(item.structuredidentifier)
=> "ISO1(allparts): All Parts"
----


=== XML serialization

[source,ruby]
----
item.to_xml(bibdata: true)
=> "<bibdata>
  <fetched>2018-10-21</fetched>
  <title type="title-main" format="text/plain" language="en" script="Latn">Metadata</title>
  <title type="title-intro" format="text/plain" language="en" script="Latn">Geographic information</title>
  <title type="title-part" format="text/plain" language="en" script="Latn">Part 1: Fundamentals</title>
  <title type="main" format="text/plain" language="en" script="Latn">Metadata - Geographic information - Part 1: Fundamentals</title>
  <title type="title-main" format="text/plain" language="fr" script="Latn">Métadonnées</title>
  <title type="title-intro" format="text/plain" language="fr" script="Latn">Information géographique</title>
  <title type="title-part" format="text/plain" language="fr" script="Latn">Information géographique</title>
  <title type="main" format="text/plain" language="fr" script="Latn">Métadonnées - Information géographique - Information géographique</title>
  <uri type="src">https://www.iso.org/standard/53798.html</uri>
  <uri type="obp">https://www.iso.org/obp/ui/#!iso:std:53798:en</uri>
  <uri type="rss">https://www.iso.org/contents/data/standard/05/37/53798.detail.rss</uri>
  <docnumber>123456</docnumber>
  <date type="published">
    <on>2014</on>
  </date>
  <contributor>
    <role type="publisher"/>
    <organization>
      <name>International Organization for Standardization</name>
      <abbreviation>ISO</abbreviation>
      <uri>www.iso.org</uri>
    </organization>
  </contributor>
  <contributor>
    <role type="author"/>
    <person>
      <name>
        <completename>John Smith</completename>
      </name>
    </person>
  </contributor>
  <edition>1</edition>
  <version>
    <revision_date>2019-04-01</revision_date>
    <draft>draft</draft>
  </version>
  <language>en</language>
  <language>fr</language>
  <script>Latn</script>
  <abstract format="text/plain" language="en" script="Latn">ISO 19115-1:2014 defines the schema required for ...</abstract>
  <abstract format="text/plain" language="fr" script="Latn">L'ISO 19115-1:2014 définit le schéma requis pour ...</abstract>
  <status>
    <stage>60</stage>
    <substage>60</substage>
  </status>
  <copyright>
    <from>2014</from>
    <owner>
      <organization>
        <name>International Organization for Standardization</name>
        <abbreviation>ISO</abbreviation>
        <uri>www.iso.org</uri>
      </organization>
    </owner>
  </copyright>
  <relation type="updates">
    <bibitem>
      <formattedref>ISO 19115:2003</formattedref>
      <status>
        <stage>60</stage>
        <substage>60</substage>
      </status>
    </bibitem>
    <locality type="updates">
      <referenceFrom>Reference form</referenceFrom>
    </locality>
  </relation>
  <relation type="updates">
    <bibitem>
      <formattedref>ISO 19115:2003/Cor 1:2006</formattedref>
    </bibitem>
  </relation>
  <series type="main">
    <title type="title-main" language="en" script="Latn">ISO/IEC FDIS 10118-3</title>
    <place>Serie's place</place>
    <organization>Serie's organization</organization>
    <abbreviation language="en" script="Latn">ABVR</abbreviation>
    <from>2009-02-01</from>
    <to>2010-12-20</to>
    <number>serie1234</number>
    <partnumber>part5678</partnumber>
  </series>
  <series type="alt">
    <formattedref language="en" script="Latn">serieref</formattedref>
  </series>
  <medium>
    <form>medium form</form>
    <size>medium size</size>
    <scale>medium scale</scale>
  </medium>
  <place>bib place</place>
  <locality type="section">
    <referenceFrom>Reference from</referenceFrom>
    <referenceTo>Reference to</referenceTo>
  </locality>
  <accesslocation>accesslocation1</accesslocation>
  <accesslocation>accesslocation2</accesslocation>
  <classification type="type">value</classification>
  <validity>
    <validityBegins>2010-10-10 12:21</validityBegins>
    <validityEnds>2011-02-03 18:30</validityEnds>
    <validityRevision>2011-03-04 09:00</validityRevision>
  </validity>
  <ext>
    <doctype>international-standard</doctype>
    <editorialgroup>
      <technical_committee number="211" type="technicalCommittee"> ISO/TC 211 Geographic information/Geomatics</technical_committee>
      <subcommittee number="122" type="ISO">International Organization for Standardization</subcommittee>
      <workgroup number="111" type="WG">Workgroup Organization</workgroup>
    </editorialgroup>
    <ics>
      <code>35.240.70</code>
      <text>IT applications in science</text>
    </ics>
    <structuredidentifier type="sid">
      <project-number part="2" subpart="2">ISO 1-2:2014</project-number>
    </structuredidentifier>
  </ext>
</bibdata>"

item.to_xml(bibdata: true, note: [{ type: "note type", text: "test note" }])
=> "<bibdata>
  <fetched>2018-10-21</fetched>
  <title type="title-main" format="text/plain" language="en" script="Latn">Metadata</title>
  ...
  <note format="text/plain" type="note type">test note</note>
  ...
----

=== Create bibliographic item form YAML
[source,ruby]
----
hash = YAML.load_file 'spec/examples/iso_bib_item.yml'
=> {"id"=>"ISO/TC211",
...

bib_hash = RelatonIsoBib::HashConverter.hash_to_bib hash
=> {:id=>"ISO/TC211",
...

RelatonIsoBib::IsoBibliographicItem.new bib_hash
=> #<RelatonIsoBib::IsoBibliographicItem:0x007fdb95ba98e8
...
----

== BibliographicItem

The ISO standards use a subset of the generic bibliographic fields specified in the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model]:

* Title:
** English; French
** titleIntro; titleMain; titlePart
* DocIdentifier:
** project number; part number; technical committee document number
* Source: the ISO page from which the standard may be purchased or downloaded
* Type: IsoDocumentType (International Standard, Technical Specification, Technical Report, Publicly Available Specification, International Workshop Agreement, Guide)
* Project Group:
** Technical Committee, Subcommittee, Workgroup, Secretariat
** Technical Committee Number, Subcommittee Number, Workgroup Number
** Technical Committee Type, Subcommittee Type, Workgroup Type (e.g. JTC)
** Organization:Name (ISO; other standards organisations, for standards jointly published with ISO)
* ICS: refer https://www.iso.org/publication/PUB100033.html
* Status
** Stage, Substage
* Edition
* Date:Published
* Abstract
* Relations
** Obsoletes, Updates

All FormattedString instances are returned by default as  a text/plain string; if required, they are returned as a text/html string.

== Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/relaton-iso-bib.

== License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).