= RelatonIso: retrieve ISO Standards for bibliographic use using the BibliographicItem model image:https://img.shields.io/gem/v/relaton-iso.svg["Gem Version", link="https://rubygems.org/gems/relaton-iso"] image:https://github.com/relaton/relaton-iso/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/relaton/relaton-iso/actions?workflow=macos"] image:https://github.com/relaton/relaton-iso/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/relaton/relaton-iso/actions?workflow=windows"] image:https://github.com/relaton/relaton-iso/workflows/ubuntu/badge.svg["Build Status (Ubuntu)", link="https://github.com/relaton/relaton-iso/actions?workflow=ubuntu"] image:https://codeclimate.com/github/relaton/relaton-iso/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/relaton-iso"] image:https://img.shields.io/github/issues-pr-raw/relaton/relaton-iso.svg["Pull Requests", link="https://github.com/relaton/relaton-iso/pulls"] image:https://img.shields.io/github/commits-since/relaton/relaton/latest.svg["Commits since latest",link="https://github.com/relaton/relaton/releases"] RelatonIso is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model]. You can use it to retrieve metadata of ISO Standards from https://www.iso.org, and access such metadata through the `IsoBibliographicItem` object. == Installation Add this line to your application's Gemfile: [source,ruby] ---- gem 'relaton-iso' ---- And then execute: $ bundle Or install it yourself as: $ gem install relaton-iso == Usage === Configuration Configuration is optional. The available option is `logger` which is a `Logger` instance. By default, the logger is `Logger.new($stderr)` with `Logger::WARN` level. To change the logger level, use `RelatonIso.configure` block. [source,ruby] ---- require 'relaton_iso' => true RelatonIso.configure do |config| config.logger.level = Logger::DEBUG end ---- === Search for standards using keywords [source,ruby] ---- hit_collection = RelatonIso::IsoBibliography.search("ISO 19115") => hit_collection.first => item = hit_collection[2].fetch => # [# "urn:iso:std:iso:19115:-1:ed-1:stage-60.60:amd:2020:v2" ---- === Fetch document by reference and year [source,ruby] ---- item = RelatonIso::IsoBibliography.get "ISO 19115:2003" [relaton-iso] (ISO 19115:2003) Fetching from iso.org ... [relaton-iso] (ISO 19115:2003) Found: `ISO 19115:2003` => # # "ISO 19115:2003" ---- === Fetch non-part document [source,ruby] ---- item = RelatonIso::IsoBibliography.get "ISO 19115" [relaton-iso] (ISO 19115) Fetching from iso.org ... [relaton-iso] (ISO 19115) Found: `ISO 19115:2003` => # "ISO 19115" ---- === Fetch a part document [source,ruby] ---- item = RelatonIso::IsoBibliography.get "ISO 19115-1" [relaton-iso] (ISO 19115-1) Fetching from iso.org ... [relaton-iso] (ISO 19115-1) Found: `ISO 19115-1:2014` => # "ISO 19115-1" ---- === Fetch all-parts document [source,ruby] ---- item = RelatonIso::IsoBibliography.get "ISO 19115 (all parts)" [relaton-iso] (ISO 19115) Fetching from iso.org ... [relaton-iso] (ISO 19115) Found: `ISO 19115` => # # "ISO 19115 (all parts)" item = RelatonIso::IsoBibliography.get "ISO 19115-1 (all parts)" [relaton-iso] (ISO 19115) Fetching from iso.org ... [relaton-iso] (ISO 19115) Found: `ISO 19115` => # # "ISO 19115 (all parts)" ---- === Non-standard ISO/IEC documents ==== General ISO/IEC Directives and related documents are fetched from the `relaton-data-iso` repository managed by the Relaton team. The following PubID patterns are used to fetch particular documents. ==== ISO/IEC Directives in Parts `ISO/IEC DIR 1 ISO SUP`:: ISO/IEC Directives, Consolidated ISO Supplement -- Procedures specific to ISO. This is the undated reference. `ISO/IEC DIR 1 ISO SUP:{yyyy}`::: Available edition years from 2003 (ed1) to 2023 (ed14). `ISO/IEC DIR 1`:: ISO/IEC Directives, Part 1. This is the undated reference. `ISO/IEC DIR 1 ISO`:: ISO-published version of "ISO/IEC Directives, Part 1". `ISO/IEC DIR 1 ISO:{yyyy}`::: Edition years from 1986 (ed1) to 2023 (ed19). `ISO/IEC DIR 1 IEC`:: IEC-published version of "ISO/IEC Directives, Part 1" `ISO/IEC DIR 1 IEC:{yyyy}`::: Edition years from 1986 (ed1) to 2023 (ed19). `ISO/IEC DIR 2`:: ISO/IEC Directives, Part 2. This is the undated reference. `ISO/IEC DIR 2 ISO`:: ISO-published version of "ISO/IEC Directives, Part 2" `ISO/IEC DIR 2 ISO:{yyyy}`::: Edition years from 1986 (ed1) to 2021 (ed9). `ISO/IEC DIR 2 IEC`:: IEC-published version of "ISO/IEC Directives, Part 2" `ISO/IEC DIR 2 IEC:{yyyy}`::: Edition years from 1986 (ed1) to 2021 (ed9). `ISO/IEC DIR 3`:: ISO/IEC Directives, Part 3. This is the undated reference. This is of historical interest, as originally ISO/IEC published the Directives in 3 parts: Part 1 "Procedures for the technical work", Part 2 "Methodology for the development of International Standards", Part 3 "Drafting and presentation of International Standards". In the 2004 versions, Parts 1 and 2 merged into the new Part 1, and Part 3 was renamed as Part 2. `ISO/IEC DIR 3:{yyyy}`::: Edition years: 1986 (ed1), 1989 (ed2), 1997 (ed3). ==== ISO/IEC Directives ISO Supplements related `ISO/IEC DIR 1 ISO SUP`:: ISO/IEC Directives, Consolidated ISO Supplement -- Procedures specific to ISO. This is the undated reference. `ISO/IEC DIR 1 ISO SUP:{yyyy}`::: Available edition years from 2003 (ed1) to 2023 (ed14). ==== ISO/IEC Directives IEC Supplements related `ISO/IEC DIR IEC SUP`:: ISO/IEC Directives, IEC Supplement -- Procedures specific to IEC. This is the undated reference. `ISO/IEC DIR IEC SUP:{yyyy}`::: Available edition years from 2009 (ed4) to 2023 (ed17). `ISO/IEC DIR 1 + IEC SUP`:: The consolidated version of "ISO/IEC Directives, Part 1 + IEC Supplement -- Procedures specific to IEC". This is the undated reference. `ISO/IEC DIR 1 + IEC SUP:{yyyy}`::: Available edition years from 2016 (ed12) to 2023 (ed19). ==== ISO/IEC JTC 1 governance documents `ISO/IEC JTC 1 DIR`:: ISO/IEC JTC 1 Directives. This is the undated reference. Notice that these are "internal directives" of ISO/IEC JTC 1. This series existed until 2007, after which it became "ISO/IEC Directives -- JTC 1 Supplement". `ISO/IEC JTC 1 DIR:{yyyy}`::: Available edition years are: 2004 (5th Edition), 2005 (5th Edition, Version 1.0), 2006 (5th Edition, Version 2.0), 2007 (5th Edition, Version 3.0). `ISO/IEC DIR JTC 1`:: ISO/IEC Directives, JTC 1 Supplement -- Procedures specific to JTC 1. This is the undated reference. `ISO/IEC DIR JTC 1:{yyyy}`::: Available edition years from 2010 (ed1) to 2023 (ed12). ==== ISO/TC 184/SC 4 important N-documents `ISO/TC 184/SC 4 N2412`:: ISO/TC 184/SC 4 Supplementary directives - Rules for the structure and drafting of SC 4 standards for industrial data. 2008-12-16. `ISO/TC 184/SC 4 N2412`:: ISO/TC 184/SC 4 Supplementary directives - Rules for the structure and drafting of SC 4 standards for industrial data. 2020-07-31. `ISO/TC 184/SC 4 N3500`:: ISO/TC 184/SC 4 Handbook -- SC 4 Supplement to ISO directives. 2020-08-09. === XML serialization Possible options: - *bibdata* - If true then wrapp item with _bibdata_ element and add _ext_ element. - *note* - Array of hashes `{ text: "Note", type: "note" }`. These notes will be added to XML. [source,ruby] ---- item.to_xml => " 2022-12-04 Geographic information Metadata ... " item.to_xml bibdata: true => " 2022-12-04 Geographic information ... international-standard ... " item.to_xml note: [{ text: "Note", type: "note" }] => " ... Note ... " ---- === Get specific language [source,ruby] ---- item.title lang: 'en' => #, @type="title-intro">, #, @type="title-main">, #, @type="main">]> item.title lang: 'fr' => #, @type="title-intro">, #, @type="title-main">, #, @type="main">]> item = RelatonIso::IsoBibliography.get "ISO 19115:2003" [relaton-iso] (ISO 19115:2003) Fetching from iso.org ... [relaton-iso] (ISO 19115:2003) Found: `ISO 19115:2003` => # # ---- === Typed links Each ISO document has `src` type link and optional `obp`, `rss`, and `pub` link types. [source,ruby] ---- item.link => [#, @language=nil, @script=nil, @type="src">, #, @language=nil, @script=nil, @type="rss">] ---- == 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). == Exceptional Citations This gem retrieves bibliographic descriptions of ISO documents by doing searches on the ISO website, http://www.iso.org, and screenscraping the document that matches the queried document identifier. The following documents are not returned as search results from the ISO website, and the gem returns manually generated references to them. * `IEV`: used in the metanorma-iso gem to reference Electropedia entries generically. Is resolved to an "all parts" reference to IEC 60050, which in turn is resolved into the specific documents cited by their top-level clause. == Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/relaton-iso == License The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT license].