= RelatonBib
image:https://img.shields.io/gem/v/relaton-bib.svg["Gem Version", link="https://rubygems.org/gems/relaton-bib"]
image:https://github.com/relaton/relaton-bib/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/relaton/relaton-bib/actions?workflow=macos"]
image:https://github.com/relaton/relaton-bib/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/relaton/relaton-bib/actions?workflow=windows"]
image:https://github.com/relaton/relaton-bib/workflows/ubuntu/badge.svg["Build Status (Ubuntu)", link="https://github.com/relaton/relaton-bib/actions?workflow=ubuntu"]
image:https://codeclimate.com/github/relaton/relaton-bib/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/relaton/relaton-bib"]
image:https://img.shields.io/github/issues-pr-raw/relaton/relaton-bib.svg["Pull Requests", link="https://github.com/relaton/relaton-bib/pulls"]
image:https://img.shields.io/github/commits-since/relaton/relaton-bib/latest.svg["Commits since latest",link="https://github.com/relaton/relaton-bib/releases"]
RlatonBib is a Ruby gem that implements the https://github.com/metanorma/relaton-models#bibliography-uml-models[BibliographicItem model].
== Installation
Add this line to your application's Gemfile:
[source,ruby]
----
gem 'relaton-bib'
----
And then execute:
$ bundle
Or install it yourself as:
$ gem install relaton-bib
== Usage
=== Create bibliographic item
[source,ruby]
----
item = RelatonBib::BibliographicItem.new(
id: "ISOTC211", fetched: Date.today.to_s,
title: [
{ type: "main", content: "Geographic information", language: "en", script: "Latn" },
{
content: "Information géographique", language: "fr", script: "Latn"
},
],
type: "standard",
docid: [
RelatonBib::DocumentIdentifier.new(id: "TC211", type: "ISO"),
RelatonBib::DocumentIdentifier.new(id: "ISBN", type: "isbn"),
RelatonBib::DocumentIdentifier.new(id: "LCCN", type: "lccn"),
RelatonBib::DocumentIdentifier.new(id: "ISSN", type: "issn"),
],
docnumber: "123456",
edition: "1", language: %w[en fr], script: ["Latn"],
version: RelatonBib::BibliographicItem::Version.new("2019-04-01", ["draft"]),
biblionote: [
RelatonBib::BiblioNote.new(content: "note"),
RelatonBib::BiblioNote.new(content: "An note", type: "annote"),
RelatonBib::BiblioNote.new(content: "How published", type: "howpublished"),
RelatonBib::BiblioNote.new(content: "Comment", type: "comment"),
RelatonBib::BiblioNote.new(content: "Table Of Contents", type: "tableOfContents"),
],
docstatus: RelatonBib::DocumentStatus.new(
stage: "stage", substage: "substage", iteration: "final",
),
date: [
{ type: "issued", on: "2014" },
{ type: "published", on: "2014-04" },
{ type: "accessed", on: "2015-05-20" },
],
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", subdivision: "division",
},
role: [{ type: "publisher", description: ["Publisher role"] }],
},
{
entity: RelatonBib::Person.new(
name: RelatonBib::FullName.new(
completename: RelatonBib::LocalizedString.new("A. Bierman", "en"),
),
affiliation: [RelatonBib::Affilation.new(
organization: RelatonBib::Organization.new(
name: "IETF",
abbreviation: RelatonBib::LocalizedString.new("IETF"),
identifier: [RelatonBib::OrgIdentifier.new("uri", "www.ietf.org")],
)
)],
contact: [
RelatonBib::Address.new(
street: ["Street"], city: "City", postcode: "123456",
country: "Country", state: "State"
),
RelatonBib::Contact.new(type: "phone", value: "223322"),
]
),
role: [type: "author"],
},
RelatonBib::ContributionInfo.new(
entity: RelatonBib::Organization.new(
name: "IETF",
abbreviation: "IETF",
identifier: [RelatonBib::OrgIdentifier.new("uri", "www.ietf.org")],
),
role: [type: "publisher"],
),
{
entity: RelatonBib::Person.new(
name: RelatonBib::FullName.new(
initial: [RelatonBib::LocalizedString.new("A.", "en")],
surname: RelatonBib::LocalizedString.new("Bierman", "en"),
forename: [RelatonBib::LocalizedString.new("Forename", "en")],
addition: [RelatonBib::LocalizedString.new("Addition", "en")],
prefix: [RelatonBib::LocalizedString.new("Prefix", "en")],
),
affiliation: [RelatonBib::Affilation.new(
organization: RelatonBib::Organization.new(name: "IETF", abbreviation: "IETF"),
description: [RelatonBib::LocalizedString.new("Description", "en")]
)],
contact: [
RelatonBib::Address.new(
street: ["Street"], city: "City", postcode: "123456",
country: "Country", state: "State"
),
RelatonBib::Contact.new(type: "phone", value: "223322"),
],
identifier: [RelatonBib::PersonIdentifier.new("uri", "www.person.com")],
),
role: [type: "author"],
},
{ entity: { name: "Institution" }, role: [type: "sponsor"] }
],
copyright: { owner: {
name: "International Organization for Standardization",
abbreviation: "ISO", url: "www.iso.org"
}, from: "2014", to: "2020" },
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" },
{ type: "doi", content: "http://standrd.org/doi-123" },
{ type: "file", content: "file://path/file" },
],
relation: [
{
type: "updates",
bibitem: RelatonBib::BibliographicItem.new(
formattedref: RelatonBib::FormattedRef.new(content: "ISO 19115:2003"),
),
bib_locality: [
RelatonBib::BibItemLocality.new("section", "Reference from"),
],
},
{
type: "updates",
bibitem: RelatonBib::BibliographicItem.new(
type: "standard",
formattedref: RelatonBib::FormattedRef.new(content: "ISO 19115:2003/Cor 1:2006"),
),
},
{
type: "partOf",
bibitem: RelatonBib::BibliographicItem.new(
title: [RelatonBib::TypedTitleString.new(type: "main", content: "Book title")],
),
},
],
series: [
RelatonBib::Series.new(
type: "main",
title: RelatonBib::TypedTitleString.new(
type: "original", content: "ISO/IEC FDIS 10118-3", language: "en",
script: "Latn", format: "text/plain",
),
place: "Serie's place",
organization: "Serie's organization",
abbreviation: RelatonBib::LocalizedString.new("ABVR"),
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",
),
),
RelatonBib::Series.new(
type: "journal", title: RelatonBib::TypedTitleString.new(content: "Journal"), number: "7"
),
RelatonBib::Series.new(title: RelatonBib::TypedTitleString.new(content: "Series")),
],
medium: RelatonBib::Medium.new(
form: "medium form", size: "medium size", scale: "medium scale",
),
place: [
"bib place",
RelatonBib::Place.new(name: "Geneva", uri: "geneva.place", region: "Switzelznd")
],
extent: [
RelatonBib::BibItemLocality.new("section", "Reference from", "Reference to"),
RelatonBib::BibItemLocality.new("chapter", "4"),
RelatonBib::BibItemLocality.new("page", "10", "20"),
RelatonBib::BibItemLocality.new("volume", "1"),
],
accesslocation: ["accesslocation1", "accesslocation2"],
classification: [
RelatonBib::Classification.new(type: "type", value: "value"),
RelatonBib::Classification.new(type: "keyword", value: "Keywords"),
RelatonBib::Classification.new(type: "mendeley", value: "Mendeley Tags"),
],
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),
)
)
----
=== BibliographicItem Typed Title Strings
[source,ruby]
----
item.title
=> [#<RelatonBib::TypedTitleString:0x007fa49a360290
@title=#<RelatonBib::FormattedString:0x007fa49a360088 @content="Geographic information", @format=nil, @language=["en"], @script=["Latn"]>,
@type="main">,
#<RelatonBib::TypedTitleString:0x007fa49a35bf38
@title=#<RelatonBib::FormattedString:0x007fa49a35bdd0 @content="Information géographique", @format=nil, @language=["fr"], @script=["Latn"]>,
@type=nil>]
----
=== BibliographicItem Formatted Strings
[source,ruby]
----
item.abstract
=> [#<RelatonBib::FormattedString:0x007fa49a35aed0 @content="ISO 19115-1:2014 defines the schema required for ...", @format="text/plain", @language=["en"], @script=["Latn"]>,
#<RelatonBib::FormattedString:0x007fa49a35ae08 @content="L'ISO 19115-1:2014 définit le schéma requis pour ...", @format="text/plain", @language=["fr"], @script=["Latn"]>]
item.abstract(lang: "en").to_s
=> "ISO 19115-1:2014 defines the schema required for ..."
"
----
=== BibliographicItem references
[source,ruby]
----
item.shortref item
=> "ISO/TC211:2014"
----
=== XML serialization
[source,ruby]
----
item.to_xml
=> "<bibitem id=\"ISO/TC211\" type=\"standard\">
<fetched>2019-04-30</fetched>
<title type=\"main\" language=\"en\" script=\"Latn\">Geographic information</title>
<title language=\"fr\" script=\"Latn\">Information géographique</title>
...
</bibitem>"
----
Default root element is `bibitem`. With argument `bibdata: true` the XML wrapped with `bibdata` element.
[source,ruby]
----
item.to_xml
=> "<bibitem id=\"ISO/TC211\" type=\"standard\">
<fetched>2019-04-30</fetched>
<title type=\"main\" language=\"en\" script=\"Latn\">Geographic information</title>
...
</bibdata>"
----
==== Date format
By default date elements are formatted as year (yyyy). Option `:date_format` allows to output date elements in `:short` (yyyy-mm) and `:full` (yyyy-mm-dd) additiona formats.
[surce,ruby]
----
item.to_xml date_format: :short
=> "<bibitem id=\"ISO/TC211\" type=\"standard\">
<fetched>2019-04-30</fetched>
<title type=\"main\" language=\"en\" script=\"Latn\">Geographic information</title>
...
<date type="issued">
<on>2014-01</on>
</date>
<date type="published">
<on>2014-04</on>
</date>
<date type="accessed">
<on>2015-05</on>
</date>
...
item.to_xml date_format: :full
=> "<bibitem id=\"ISO/TC211\" type=\"standard\">
...
<date type="issued">
<on>2014-01-01</on>
</date>
<date type="published">
<on>2014-04-01</on>
</date>
<date type="accessed">
<on>2015-05-20</on>
</date>
...
----
=== Create bibliographic item form YAML
[source,ruby]
----
hash = YAML.load_file 'spec/examples/bib_item.yml'
=> {"id"=>"ISO/TC211",
...
bib_hash = RelatonBib::HashConverter.hash_to_bib hash
=> {:id=>"ISO/TC211",
...
RelatonBib::BibliographicItem.new bib_hash
=> #<RelatonBib::BibliographicItem:0x007ff1524f8c88
...
----
=== Export bibliographic item to Hash
[source,ruby]
----
item.to_hash
=> {"id"=>"ISOTC211",
"title"=>
[{"type"=>"main", "content"=>"Geographic information", "language"=>"en", "script"=>"Latn", "format"=>"text/plain"},
{"content"=>"Information géographique", "language"=>"fr", "script"=>"Latn", "format"=>"text/plain"}],
...
----
=== Create bibliographic item from BibTeX
[source,ruby]
----
RelatonBib::BibtexParser.from_bibtex File.read('spec/examples/bibitem.bib')
=> {"ISOTC211"=>
#<RelatonBib::BibliographicItem:0x007fedee0a2ab0
...
----
=== Export bibliographic item to BibTeX
[source,ruby]
----
item.to_bibtex
@misc{ISOTC211,
tile = {Geographic information},
edition = {1},
author = {Bierman, A. and Bierman, Forename},
...
----
== 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/metanorma/relaton-bib.
== License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).