relaton 3.0.0.pre.alpha.16 → 3.0.0.pre.alpha.18

data/lib/relaton/bipm/README.adoc

@@ -0,0 +1,352 @@
+= RelatonBipm: retrieve BIPM Standards for bibliographic use using the BibliographicItem model
+
+RelatonBipm 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 BIPM Standards from https://www.bipm.org, and access such metadata through the `BipmBibliographicItem` object.
+
+== Usage
+
+=== Search for a standard using keywords
+
+==== References for Si-Brochure documents
+
+`BIPM {DOCUMENT_NAME}`
+
+Allowed document names are:
+
+- CCEM-GD-RSI-1
+- CCL-GD-MeP-1
+- CCL-GD-MeP-2
+- CCL-GD-MeP-3
+- CCM-GD-RSI-1
+- CCM-GD-RSI-2
+- SI MEP A1
+- SI MEP Cd1
+- Rapport BIPM-2019/05
+- SI MEP KUPRTM
+- SI MEP KAPRT
+- SI MEP K1
+- SI MEP KLJNT
+- SI MEP KRPRT
+- SI MEP Kg1
+- SI MEP M1
+- SI MEP Mol1
+- SI MEP S1
+- SI Brochure
+- SI Brochure, Appendix 4
+
+==== Reference structure for Metrologia documents
+
+`BIPM Metrologia {JOURNAL} {VOLUME} {ISSUE}`
+
+- `{JOURNAL}` - journal number, optional
+- `{VOLUME}` - volume number, optional
+- `{ISSUE}` - issue number, optional
+
+==== Reference structures for Outcomes documents
+
+===== Basic pattern
+
+----
+Long:
+{group name} -- {type} {number} ({year})
+{group name} {type} {number} ({year})
+{group name} {type} {year}-{zero_leading_number}
+
+Short:
+{group name} -- {type-abbrev} {number} ({year}, {lang})
+{group name} {type-abbrev} {number} ({year}, {lang})
+----
+
+- `group name` - a name of the group, required. A full list of group names is available https://github.com/metanorma/bipm-editor-guides/blob/main/sources/bipm-references-en.adoc#appendix-a-bipm-groups-and-codes[here].
+- `type` - a type of document, required. A list of types is: Resolution (Résolution), Recommendation (Recommandation), Decision (Décision), Meeting (Réunion), Declaration (Déclaration).
+- `type-abbrev` - an abbreviation of the type, required. A list of abbreviations: RES (Resolution), REC (Recommendation), DECN (Decision).
+- `number` - a number of the document, optional. Can be with part, e.g. `1-2`.
+- `zero_leading_number` - a number of the document with a leading zero, required. Can be used when a document has a 1 or 2 digits number. It's `00` for documents without a number.
+- `year` - a year of the document, optional.
+- `lang` - a language of the document, optional. Can be `EN` or `FR`.
+
+===== Special case pattern
+
+The basic pattern works fine for all, except for these 2 cases:
+
+- Decisions of the CIPM (since 2012)
+- Recommendations/Resolutions/Decisions of the JCRB
+
+Where the committee name is part of the outcome identifier. +
+Special cases:
+
+----
+Decision CIPM/111-10 (2022) / Décision CIPM/111-10 (2022)
+Recommendation JCRB/43-1 (2021) / Recommandation JCRB/43-1 (2021)
+----
+
+===== Single language version (English)
+
+`type` can be:
+
+- Resolution (RES)
+- Recommendation (REC)
+- Decision (DECN)
+- Statement (DECL)
+
+e.g.
+
+----
+CCTF -- Recommendation 2 (1970)
+CCTF -- REC 2 (1970, EN)
+----
+
+Special cases:
+
+----
+Decision CIPM/111-10 (2022)
+CIPM DECN CIPM/111-10 (2022, EN)
+Recommendation JCRB/43-1 (2021)
+JCRB REC JCRB/43-1 (2021, EN)
+----
+
+===== Single language version (French)
+
+`type` can be:
+
+- Résolution (RES)
+- Recommandation (REC)
+- Décision (DECN)
+- Déclaration (DECL)
+
+e.g.
+
+----
+CCTF -- Recommandation 2 (1970)
+CCTF -- REC 2 (1970, FR)
+----
+
+Special cases:
+
+----
+Décision CIPM/111-10 (2022)
+CIPM DECN CIPM/111-10 (2022, FR)
+Recommandation JCRB/43-1 (2021)
+JCRB REC JCRB/43-1 (2021, FR)
+----
+
+===== Dual language version (language independent version)
+
+`type` can be in their respective languages or the following abbreviations:
+
+- RES
+- REC
+- DECN
+- DECL
+
+----
+CCTF -- Recommandation 2 (1970) / Recommendation 2 (1970)
+CCTF REC 2 (1970)
+----
+
+Special cases:
+
+----
+Decision CIPM/110-10 (2022) / Décision CIPM/111-10 (2022)
+CIPM DECN CIPM/110-10 (2022)
+Recommendation JCRB/43-1 (2021) / Recommandation JCRB/43-1 (2021)
+JCRB REC JCRB/43-1 (2021)
+----
+
+==== Examples
+
+[source,ruby]
+----
+require "relaton_bipm"
+=> true
+
+# get BIPM brochure
+item = RelatonBipm::BipmBibliography.get "BIPM SI Brochure"
+[relaton-bipm] (BIPM SI Brochure) Fetching from Relaton repository ...
+[relaton-bipm] (BIPM SI Brochure) Found: `BIPM SI Brochure`
+=> #<RelatonBipm::BipmBibliographicItem:0x007ffb83982fe8
+...
+
+# get BIPM Metrologia page
+bib = RelatonBipm::BipmBibliography.get "BIPM Metrologia 29 6 001"
+[relaton-bipm] (BIPM Metrologia 29 6 001) Fetching from Relaton repository ...
+[relaton-bipm] (BIPM Metrologia 29 6 001) Found: `Metrologia 29 6 001`
+=> #<RelatonBipm::BipmBibliographicItem:0x007f8857f94d40
+...
+
+# get CGPM meetings
+RelatonBipm::BipmBibliography.get "CGPM 1st Meeting (1889)"
+[relaton-bipm] (CGPM 1st Meeting (1889)) Fetching from Relaton repository ...
+[relaton-bipm] (CGPM 1st Meeting (1889)) Found: `CGPM 1th meeting (1889)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f7fd02aba28
+...
+
+# get CGPM resolutions
+RelatonBipm::BipmBibliography.get "CGPM RES (1889, E)"
+[relaton-bipm] (CGPM RES (1889, E)) Fetching from Relaton repository ...
+[relaton-bipm] (CGPM RES (1889, E)) Found: `CGPM RES (1889)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f80421f93d8
+...
+
+RelatonBipm::BipmBibliography.get "CGPM Resolution (1889)"
+[relaton-bipm] (CGPM Resolution (1889)) Fetching from Relaton repository ...
+[relaton-bipm] (CGPM Resolution (1889)) Found: `CGPM RES (1889)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f8017f60c18
+...
+
+RelatonBipm::BipmBibliography.get "CGPM Résolution (1889)"
+[relaton-bipm] (CGPM Résolution (1889)) Fetching from Relaton repository ...
+[relaton-bipm] (CGPM Résolution (1889)) Found: `CGPM RES (1889)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f8017f492e8
+...
+
+# get CIPM decision by year and decision number
+RelatonBipm::BipmBibliography.get "BIPM Decision CIPM/101-1 (2012)"
+[relaton-bipm] (BIPM Decision CIPM/101-1 (2012)) Fetching from Relaton repository ...
+[relaton-bipm] (BIPM Decision CIPM/101-1 (2012)) Found: `CIPM DECN 101-1 (2012)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f8017f2bd88
+...
+
+RelatonBipm::BipmBibliography.get "BIPM DECN CIPM/101-1 (2012, E)"
+[relaton-bipm] (BIPM DECN CIPM/101-1 (2012, E)) Fetching from Relaton repository ...
+[relaton-bipm] (BIPM DECN CIPM/101-1 (2012, E)) Found: `CIPM DECN 101-1 (2012)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f8017f39438
+...
+
+# get CIPM recommendation
+RelatonBipm::BipmBibliography.get "CIPM Recommendation 1 (2005)"
+[relaton-bipm] (CIPM Recommendation 1 (2005)) Fetching from Relaton repository ...
+[relaton-bipm] (CIPM Recommendation 1 (2005)) Found: `CIPM REC 1 (2005)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f8017f31da0
+...
+
+RelatonBipm::BipmBibliography.get "CIPM REC 1 (2005, FR)"
+[relaton-bipm] (CIPM REC 1 (2005, FR)) Fetching from Relaton repository ...
+[relaton-bipm] (CIPM REC 1 (2005, FR)) Found: `CIPM REC 1 (2005)`
+=> #<RelatonBipm::BipmBibliographicItem:0x00007f80422100d8
+...
+----
+
+=== XML serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="BIPMSIBrochurePart1" type="standard" schema-version="v1.2.1">
+      <fetched>2022-12-02</fetched>
+      <title type="main" format="text/plain" language="en">The International System of Units</title>
+      <title type="cover" format="text/plain" language="en">The International System of Units (SI)</title>
+      <title type="main" format="text/plain" language="fr">Le Système international d’unités</title>
+      <title type="cover" format="text/plain" language="fr">Le Système international d’unités (SI)</title>
+      <docidentifier type="BIPM" primary="true">BIPM SI Brochure</docidentifier>
+      ...
+    </bibitem>"
+----
+
+With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and adds flavor `ext` element.
+
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.2.1">
+      <fetched>2022-12-02</fetched>
+      <title type="main" format="text/plain" language="en">The International System of Units</title>
+      <title type="cover" format="text/plain" language="en">The International System of Units (SI)</title>
+      <title type="main" format="text/plain" language="fr">Le Système international d’unités</title>
+      <title type="cover" format="text/plain" language="fr">Le Système international d’unités (SI)</title>
+      <docidentifier type="BIPM" primary="true">BIPM SI Brochure</docidentifier>
+      ...
+      <ext schema-version="v1.0.0">
+        <doctype>brochure</doctype>
+        ...
+      </ext>
+    </bibdata>"
+----
+
+=== Typed links
+
+Each BIPM document has `src` type link and an optional `doi` type link.
+
+[source,ruby]
+----
+bib.link
+=> [#<RelatonBib::TypedUri:0x00007fa6d6a51728 @content=#<Addressable::URI:0xc29c URI:https://iopscience.iop.org/article/10.1088/0026-1394/29/6/001>, @type="src">,
+ #<RelatonBib::TypedUri:0x00007fa6d6a29250 @content=#<Addressable::URI:0xc2b0 URI:https://doi.org/10.1088/0026-1394/29/6/001>, @type="doi">]
+----
+
+=== Create a bibliographic item from XML
+
+[source,ruby]
+----
+RelatonBipm::XMLParser.from_xml File.read('spec/fixtures/bipm_item.xml')
+=> #<RelatonBipm::BipmBibliographicItem:0x007ffb83827a90
+...
+----
+
+=== Create a bibliographic item from YAML
+[source,ruby]
+----
+hash = YAML.load_file 'spec/fixtures/bipm_item.yml'
+=> {"id"=>"Draft-Agenda-NMI-Dir-Meeting-2017-v10",
+...
+
+RelatonBipm::BipmBibliographicItem.from_hash hash
+=> #<RelatonBipm::BipmBibliographicItem:0x007ffb668755a0
+...
+----
+
+=== Fetch data
+
+This gem uses the following datasets as data sources:
+- `bipm-data-outcomes` - looking for a local directory with the repository https://github.com/metanorma/bipm-data-outcomes
+- `bipm-si-brochute` - looking for a local directory with the repository https://github.com/metanorma/bipm-si-brochure
+- `rawdata-bipm-metrologia` - looking for a local directory with the repository https://github.com/relaton/rawdata-bipm-metrologia
+
+The method `RelatonBipm::DataFetcher.fetch(source, output: "data", format: "yaml")` fetches all the documents from the dataset and saves them to the `./data` folder in YAML format.
+Arguments:
+
+- `source` - the name of the source dataset
+- `output` - folder to save documents (default './data').
+- `format` - the format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxxml` (default `yaml`).
+
+[source,ruby]
+----
+RelatonBipm::DataFetcher.fetch "bipm-data-outcomes"
+Started at: 2022-06-23 09:36:55 +0200
+Stopped at: 2022-06-23 09:36:58 +0200
+Done in: 2 sec.
+=> nil
+
+RelatonBipm::DataFetcher.fetch "bipm-si-brochure"
+Started at: 2022-06-23 09:37:12 +0200
+Stopped at: 2022-06-23 09:37:12 +0200
+Done in: 0 sec.
+=> nil
+
+RelatonBipm::DataFetcher.fetch "rawdata-bipm-metrologia"
+Started at: 2022-06-23 09:39:12 +0200
+Stopped at: 2022-06-23 09:40:34 +0200
+Done in: 82 sec.
+=> nil
+----
+
+=== Logging
+
+RelatonBipm 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.
+
+== 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 update the index test fixture (used by tests), run `rake spec:update_index`. This downloads the latest `index-v1.zip` from the https://github.com/relaton/relaton-data-bipm[relaton-data-bipm] repository.
+
+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/relaton/relaton-bipm.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/bipm/data_fetcher.rb

@@ -63,13 +63,14 @@ module Relaton::Bipm
     # @param [Boolean, nil] warn_duplicate Warn if document already exists
     #
     def write_file(path, item, warn_duplicate: true)
-      content = serialize item
       if @files.include?(path)
         Util.warn "File #{path} already exists" if warn_duplicate
       else
         @files << path
       end
-      File.write path, content, encoding: "UTF-8"
+      # Byte-identical writes are skipped and the run records the file, so
+      # the core prune lifecycle can keep the tree between crawls.
+      force_write path, serialize(item)
     end
 
     def to_xml(item) = item.to_xml bibdata: true

data/lib/relaton/bsi/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-bsi retrieves British Standards Institution (BSI) bibliographic data using the Relaton model. Unlike index-backed flavors, it searches the BSI Shopify storefront: an **Algolia** product index finds candidate standards, then a **GraphQL** query against the Shopify storefront API fetches full metadata (titles, dates, ISBNs, committee info). Depends on relaton-iso for its ISO-based item/extension models.
+
+## Development
+
+```bash
+bundle exec rake        # default task → rspec
+bundle exec rspec spec/relaton/bsi/bibliography_spec.rb   # single file
+```
+
+(No gem-local rubocop config; the monorepo root config applies.)
+
+## Architecture
+
+Namespace: `Relaton::Bsi`. Retrieval flow:
+
+1. **Bibliography** (`lib/relaton/bsi/bibliography.rb`) — `get(code, year, opts)` / `search` entry points. Reference handling is **entirely `Pubid::Bsi`** (from the unified `pubid` gem) with **no hand-rolled identifier regex**: `parse` wraps `Pubid::Bsi::Identifier.parse` and **raises** on an unparseable query (only `Hit#pubid` rescues to nil — the Algolia catalogue carries codes such as `BS 381C SET:1996 (R2002)`, and one such row must not abort the search), `publication_year` reads `pubid.root.year` (not `base_document.year`: pubid holds an adopted standard such as `BS EN ISO 8848:2021` in `base`, so its `base_document.year` is nil; over pubid's 1,536 parseable BSI fixture ids `root.year` equals the old reader on 1,529 and fills in the base year on the other 7), and `same_reference?(query, hit, skip_rest:, drop_amd:)` decides whether a query and a candidate hit denote the same document. `same_reference?` uses only pubid's typed API — `#base_document` (peels supplements + Expert-commentary / Flex-version wrappers), `#matches?(other, ignore: %i[date month])` for the base-document comparison (`:month` is excluded alongside `:date` because Flex stores the month separately, so `exclude(:date)` alone leaves them unequal), and the `Amendment`/`Corrigendum` `#supplement_type`, `#number` and `#year` (amendment year optional when the query omits it). pubid removes the `#supplement_number`/`#supplement_year` aliases, but the locked pubid still has them and leaves a BSI supplement's `#number`/`#year` nil, so the private `supplement_number`/`supplement_year` helpers read the alias while it exists. Remove that fallback once pubid `main` has no alias. A canonical `rest_marker` (`:expert_commentary` / `:"flex_<edition>"`) makes an `ExComm` query match an `Expert Commentary` hit. `search` still lightly normalizes the **Algolia query text** (drops `BSI `, abbreviates the Expert-commentary suffix) — search-engine tuning, not identifier parsing. This depends on the `pubid` `feat/bsi-parse-gaps` work (see `HANDOFFS/metanorma__pubid.md`): the three parse/exclude gaps **plus** the Phase-2 API (`#base_document`, `exclude(:amendment|:supplement|:edition)`, uniform supplement accessors, `#matches?`).
+2. **HitCollection** (`lib/relaton/bsi/hit_collection.rb`, extends `Relaton::Core::HitCollection`) — queries the Algolia index (`shopify_products`) and filters hits by parsing each hit code and calling `Bibliography.same_reference?` against the parsed query, in three passes: exact → `skip_rest` (ignore the ExComm/Flex-version suffix) → `drop_amd` (compare base documents only, and rewrite the hit id to `hit.base_document.to_s`). Algolia keys are public/client-side.
+3. **Hit** (`lib/relaton/bsi/hit.rb`, extends `Relaton::Core::Hit`) — `item` lazy-loads the full document via the scraper; `pubid` memoizes the hit code parsed with `Pubid::Bsi` (like `Relaton::Iso::Hit#pubid`) so the three filter passes don't re-parse it, and is nil for a code pubid cannot parse. `Bibliography#results_filter` reads the year from this memoized pubid too, not from the (possibly `drop_amd`-rewritten) `hit[:code]`.
+4. **Scraper** (`lib/relaton/bsi/scraper.rb`) — GraphQL client; runs schema-based queries against the Shopify storefront GraphQL endpoint to build a full record (titles split on em-dash into intro/main/part, dates, contributors, ICS, source URI).
+5. **ItemData / Model::Item** (`item_data.rb`, `model/`) — `Relaton::Bsi::ItemData` extends `Relaton::Iso::ItemData`; `Ext` adds doctype, ICS, and a structured identifier. **Docidentifier** (`model/docidentifier.rb`) keeps the parsed `Pubid::Bsi::Identifier` as the **single stored value** of `content` (via the flavor-agnostic `Iso::Type::Pubid` lutaml type, which preserves the instance in and stringifies it out) — one source of truth: `#pubid` returns the instance, `#content` renders it to a string. `#remove_date!` → `pubid.exclude(:date, :month)`, `#remove_part!` → `pubid.exclude(:part, :subpart)`. `#to_all_parts!` wraps `pubid` in pubid's `AllParts` (`self.content = pubid.exclude(:supplement_year).to_all_parts`) — since BSI has no dedicated pubid `AllParts` subclass, the wrapper is the generic `Pubid::AllPartsIdentifier`, whose `#to_s` DOES print a "(all parts)" marker (unlike BSI's own renderer, which never had one). The `exclude(:supplement_year)` pre-step matters on a consolidated id (`BS 7273-4:2015+A1:2021`): pubid protects an `Amendment`/`Corrigendum`'s own date from a bare `exclude(:date)` — the same protection `#remove_date!` relies on to drop the base year while keeping the amendment's — but `to_all_parts`'s identity computation is built on that same `exclude`, so without the explicit `:supplement_year` key the amendment's year survives into the "(all parts)" form, distinguishing editions that marker is meant to collapse (`BS 7273+A1 (all parts)`, not `BS 7273+A1:2021 (all parts)`). Because `content` and `#pubid` are the same stored value here, both now show the "(all parts)" marker after `#to_all_parts!` — unlike flavors with a separately cached content string, which keep `content` marker-less on purpose. `#pubid`'s type check is widened to also accept `::Pubid::AllParts` (not just `Pubid::Bsi::Identifier`) for this reason. All three no-op when `#pubid` is nil. Non-BSI identifiers (e.g. ISBN) and anything pubid can't parse are stored verbatim as plain strings.
+6. **Processor** (`lib/relaton/bsi/processor.rb`) — registry integration; lazy-`require_relative`s `../bsi` in its methods.
+
+## External dependencies
+
+`algolia ~> 2.3.0`, `graphql ~> 2.3`, `graphql-client ~> 0.23`, `faraday-net_http_persistent ~> 2.0`, `relaton-core`, `relaton-iso`.
+
+## Testing
+
+RSpec with WebMock + VCR (cassettes in `spec/vcr_cassettes/`, record `:once`, 7-day re-record). Network is blocked via WebMock. No index fixture — BSI has no curated index; `spec/fixtures/` holds XML/YAML round-trip data.

data/lib/relaton/bsi/README.adoc

@@ -0,0 +1,112 @@
+= Relaton::Bsi retrieve BSI Standards for bibliographic use using the BibliographicItem model
+
+Relaton::Bsi is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].
+
+== Usage
+
+=== Search for a standard using keywords
+
+[source,ruby]
+----
+require 'relaton/bsi'
+=> true
+
+hit_collection = Relaton::Bsi::Bibliography.search("BS EN ISO 8848")
+=> <Relaton::Bsi::HitCollection:0x007fead49fe1f8 @ref=BS EN ISO 8848 @fetched=false>
+
+item = hit_collection[1].item
+=> #<Relaton::Bsi::ItemData:0x000000012ac6c9a8
+ ...
+----
+
+=== XML serialization
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="BSENISO88482021" type="standard" schema-version="v1.5.6">
+      <fetched>2025-10-18</fetched>
+      <title language="en" script="Latn" type="title-main">Small craft. Remote mechanical steering systems</title>
+      <title language="en" script="Latn" type="main">Small craft. Remote mechanical steering systems</title>
+      <uri type="src">https://shop.bsigroup.com/products/small-craft-remote-mechanical-steering-systems</uri>
+      <docidentifier type="BSI" primary="true">BS EN ISO 8848:2021</docidentifier>
+      ...
+    </bibitem>"
+----
+
+=== Typed links
+
+Each BSI document has `src` type link.
+
+[source,ruby]
+----
+item.source[0].type
+ => "src"
+
+item.source[0].content
+ => "https://shop.bsigroup.com/products/small-craft-remote-mechanical-steering-systems"
+----
+
+With `bibdata: true` option XML output wrapped with `bibdata` element and `ext` element added.
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.5.6">
+      <fetched>2025-10-18</fetched>
+      <title language="en" script="Latn" type="title-main">Small craft. Remote mechanical steering systems</title>
+      ...
+      <ext schema-version="v1.1.3">
+        <doctype>standard</doctype>
+        ...
+      </ext>
+    </bibdata>"
+----
+
+=== Get standard by code and year
+[source,ruby]
+----
+Relaton::Bsi::Bibliography.get "BS EN ISO 8848:2021"
+[relaton-bsi] INFO: (BS EN ISO 8848:2021) Fetching from shop.bsigroup.com ...
+[relaton-bsi] INFO: (BS EN ISO 8848:2021) Found: `BS EN ISO 8848:2021`
+ => #<Relaton::Bsi::ItemData:0x000000011f19b688
+...
+
+Relaton::Bsi::Bibliography.get "BS EN ISO 8848", "2021"
+[relaton-bsi] INFO: (BS EN ISO 8848) Fetching from shop.bsigroup.com ...
+[relaton-bsi] INFO: (BS EN ISO 8848) Found: `BS EN ISO 8848:2021`
+ => #<Relaton::Bsi::ItemData:0x000000011f1bdc10
+...
+----
+
+=== Create bibliographic item form YAML
+[source,ruby]
+----
+Relaton::Bsi::Item.from_yaml File.read("spec/fixtures/item.yaml", encoding: "UTF-8")
+ => #<Relaton::Bsi::ItemData:0x0000000104dd0dd8
+...
+----
+
+=== Create bibliographic item from XML
+[source,ruby]
+----
+Relaton::Bsi::Item.from_xml File.read("spec/fixtures/bibdata.xml", encoding: "UTF-8")
+ => #<Relaton::Bsi::ItemData:0x0000000104178c20
+...
+----
+
+=== Logging
+
+Relaton::Bsi 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.
+
+== 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 the created tag, 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/relaton/relaton-bsi.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).