README.adoc
= 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/rake/badge.svg["Build Status", link="https://github.com/relaton/relaton-bib/actions?workflow=rake"]
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"]
RelatonBib 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]
----
require 'relaton_bib'
=> true
hash = YAML.load_file "spec/examples/bib_item.yml"
=> {"id"=>"ISOTC211",
"fetched"=>"2022-05-02",
"title"=>["Geographic information", {"content"=>"Information géographique", "language"=>"fr", "script"=>"Latn"}],
...
item = RelatonBib::BibliographicItem.from_hash(hash)
=> #<RelatonBib::BibliographicItem:0x00007f962f030710
@abstract=
[#<RelatonBib::FormattedString:0x00007f962f02acc0
...
----
=== BibliographicItem Typed Title Strings
[source,ruby]
----
item.title
=> #<RelatonBib::TypedTitleStringCollection:0x00007fea821ec6b0
@array=
[#<RelatonBib::TypedTitleString:0x00007fea821ecb60
@title=#<RelatonBib::FormattedString:0x00007fea821eca70 @content="Geographic information", @format="text/plain", @language=nil, @script=nil>,
@type="title-main">,
#<RelatonBib::TypedTitleString:0x00007fea821ec8b8
@title=#<RelatonBib::FormattedString:0x00007fea821ec818 @content="Geographic information", @format="text/plain", @language=nil, @script=nil>,
@type="main">,
#<RelatonBib::TypedTitleString:0x00007fea821ec610
@title=
#<RelatonBib::FormattedString:0x00007fea821ec570 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
@type=nil>]>
item.title lang: "fr"
=> #<RelatonBib::TypedTitleStringCollection:0x00007fea8222d908
@array=
[#<RelatonBib::TypedTitleString:0x00007fea821ec610
@title=#<RelatonBib::FormattedString:0x00007fea821ec570 @content="Information géographique", @format="text/plain", @language=["fr"], @script=["Latn"]>,
@type=nil>]>
----
=== BibliographicItem Formatted Strings
[source,ruby]
----
item.abstract
=> [#<RelatonBib::FormattedString:0x00007fea82236828
@content="<p>ISO 19115-1:2014 defines the schema required for ...</p>",
@format="text/html",
@language=["en"],
@script=["Latn"]>,
#<RelatonBib::FormattedString:0x00007fea82236670
@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
=> "<p>ISO 19115-1:2014 defines the schema required for ...</p>"
----
=== BibliographicItem references
[source,ruby]
----
item.shortref item.docidentifier.first
=> "ISOTC211:2014"
----
=== XML serialization
[source,ruby]
----
item.to_xml
=> "<bibitem id="ISOTC211" type="standard" schema-version="v1.2.1">
<fetched>2022-05-02</fetched>
<title type="title-main" format="text/plain">Geographic information</title>
<title type="main" format="text/plain">Geographic information</title>
<title format="text/plain" language="fr" script="Latn">Information géographique</title>
...
</bibitem>"
----
The default root element is `bibitem`. With argument `bibdata: true` the XML wrapped with `bibdata` element.
[source,ruby]
----
item.to_xml bibdata: true
=> "<bibdata type="standard" schema-version="v1.2.1">
<fetched>2022-05-02</fetched>
<title type="title-main" format="text/plain">Geographic information</title>
...
<ext>
<doctype>document</doctype>
<subdoctype>subdocument</subdoctype>
...
</ext>
</bibdata>"
----
==== Date format
By default date elements are formatted as a year (yyyy). Option `:date_format` allows to output date elements in `:short` (yyyy-mm) and `:full` (yyyy-mm-dd) additional formats.
[source,ruby]
----
item.to_xml date_format: :short
=> "<bibitem id="ISOTC211" type="standard" schema-version="v1.2.1">
<fetched>2022-05-02</fetched>
<title type="title-main" format="text/plain">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>
...
</bibitem>"
item.to_xml date_format: :full
=> "<bibitem id="ISOTC211" type="standard" schema-version="v1.2.1">
...
<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>
...
</bibitem>"
----
==== Adding notes
[source,ruby]
----
item.to_xml note: [{ text: "Note", type: "note" }]
=> "<bibitem id="ISOTC211" type="standard" schema-version="v1.2.1">
...
<note format="text/plain" type="note">Note</note>
...
</bibitem>"
----
=== Create bibliographic item form YAML
[source,ruby]
----
hash = YAML.load_file 'spec/examples/bib_item.yml'
=> {"id"=>"ISOTC211"
...
RelatonBib::BibliographicItem.from_hash hash
=> #<RelatonBib::BibliographicItem:0x007ff1524f8c88
...
----
=== Create bibliographic item from BibXML
[source,ruby]
----
bibxml = File.read "spec/examples/rfc.xml"
=> <reference anchor=...
RelatonBib::BibXMLParser.parse bibxml
=> #<RelatonBib::BibliographicItem:0x00007f9d0c75b268
...
----
=== Export bibliographic item to Hash
[source,ruby]
----
item.to_hash
=> {"schema-version"=>"v1.2.1",
"id"=>"ISOTC211",
"title"=>
[{"content"=>"Geographic information", "format"=>"text/plain", "type"=>"title-main"},
{"content"=>"Geographic information", "format"=>"text/plain", "type"=>"main"},
{"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/techreport.bib')
=> {"ISOTC211"=>
#<RelatonBib::BibliographicItem:0x007fedee0a2ab0
...
----
=== Export bibliographic item to BibTeX
[source,ruby]
----
item.to_bibtex
=> @misc{ISOTC211,
title = {Geographic information},
edition = {Edition 1},
author = {Bierman, A. and Bierman, Arnold and Bierman, Arnold B},
...
----
=== Export bibliographic item to Citeproc
[source,ruby]
----
item.to_citeproc
=> [{"title"=>"Geographic information",
"edition"=>"Edition 1",
"author"=>[{"family"=>"Bierman", "given"=>"A."}, {"family"=>"Bierman", "given"=>"Arnold"}, {"family"=>"Bierman", "given"=>"Arnold B"}],
"publisher"=>"Institute of Electrical and Electronics Engineers",
"publisher-place"=>"bib place",
...
----
=== Exporting bibliographic item to AsciiBib
[source,ruby]
----
item.to_asciibib
=> [%bibitem]
== {blank}
id:: ISOTC211
fetched:: 2022-05-02
title::
title.type:: title-main
title.content:: Geographic information
title.format:: text/plain
...
----
=== Export bibliographic item to BibXML (RFC)
[source,ruby]
----
item.to_bibxml
=> "<reference anchor="ISO.TC.211" target="https://www.iso.org/standard/53798.html">
<front>
<title>Geographic information</title>
<author>
<organization abbrev="ISO">International Organization for Standardization</organization>
</author>
..
</front>
<seriesInfo name="DOI" value="10.17487/rfc1149"/>
<seriesInfo name="Internet-Draft" value="draft-ietf-somewg-someprotocol-07"/>
<seriesInfo name="ISO/IEC FDIS 10118-3" value="serie1234"/>
...
</reference>"
----
=== Logging
RelatonBib 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 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).