Gem Version Build Status Code Climate

Gem for importing and caching bibliographic references to technical standards.

Scope

The Relaton gem obtains authoritative bibliographic entries for technical standards from online sources, and expresses them in a consistent format, which can be used in document authoring. (It is the underlying bibliographic tool for the Metanorma toolset.)

The gem also caches entries it has retrieved, so that subsequent iterations do not need to go back online to retrieve the same entries. The gem uses two caches: a global cache (for all bibliographic entries retrieved by the user), and a local cache (intended to store references specific to the current document being processed.)

Entries are retrieved and stored in the Relaton bibliographic model, which is an expression of ISO 690. The subset of the model used and serialised for Relaton is defined in the iso-bib-item gem.

Entries are serialised to and from an internal data model, and multiple formats are intended to be supported. Currently only Relaton XML is supported.

Relaton imports bibliographic entries from:

  • ISO and IEC through the iso.org website, via the isobib gem

  • GB (Chinese national standards) through the GB websites, via the gbbib gem [in progress]

  • IETF standards (Internet Drafts, RFC) through the http://xml2rfc.tools.ietf.org website, via the rfcbib gem [in progress]

The gem can be extended to use other standards-specific gems. Standards-specific gems like isobib register themselves against Relaton using Relaton::Registry.instance.register, which takes as an argument a subclass of Relaton::Processor defined in the gem; see isobib/lib/relaton for an example. The processor within the standards-specific gem needs to define

  • @short, the name of the gem

  • @prefix, the regex constraining the standards code to be processed

  • get(code, date, opts), which takes a standards code, a year, and a hash of options, and returns an iso-bib-item bibliographic entry

Behaviours

  • Bibliographic entries are identified for retrieval and caching by a prefix specific to the standards class, followed by the conventional code of the standard.

    • ISO standards are identified by ISO followed by space or slash. For example, ISO/IEC DIR 2:2018

    • IEC standards are identified by IEC followed by space or slash

    • GB standards are identified by GB Standard. For example, GB Standard GM/T 0009-2012

    • IETF stadnards are identified by IETF. Foe example, IETF RFC 7991

  • If an entry is defined in both the local and the global cache, the local cache entry is used.

  • If an ISO entry has no date, the latest version available for the entry is retrieved.

  • If a cached ISO entry has no date, and was last retrieved more than 60 days ago, the gem fetches it again, in case there is a newer edition of the standard available.

  • Note that the gem does not currently support the totality of the Relaton model; it will only support the information available in the source websites. We do not expect to support cartographic information, for example.

Usage

require "relaton"
=> true

# Do not cache any entries retrieved
db = Relaton.new(nil, nil)
# Use only the global cache for any entries retrieved
db = Relaton.new("global cache filename", nil)
# Use both a local and a global cache
db = Relaton::Db.new("global cache filename", "local cache filename")
[relaton] detecting backends:
isobib
[relaton] processor "isobib" registered
=> #<Relaton::Db:...>

x = db.fetch("IEEE 19011")
"IEEE 19011 does not have a recognised prefix: /^(ISO|IEC)[ \/]|^IEV($| )/"
=> nil

x = db.fetch("ISO 19011")
fetching ISO 19011...
=> #<IsoBibItem::IsoBibliographicItem:...>

x = db.fetch("ISO 19011", "2011")
fetching ISO 19011...
=> #<IsoBibItem::IsoBibliographicItem:...>

x = db.fetch("ISO 19011", "2011", allparts: true)
fetching ISO 19011...
=> #<IsoBibItem::IsoBibliographicItem:...>

x.to_xml
=> "<bib-item type=\"international-standard\" id=\"ISO19011\">...."

db.to_xml
=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<documents>\n <bibitem type=\"international-standard\"...."

db.load_entry("ISO 19011")
=> #<IsoBibItem::IsoBibliographicItem:...>

db.save_entry("ISO 19011", nil)
=> nil

db.load_entry("ISO 19011")
=> nil