search

relaton / relaton-bib

MIT License
3 stars 1 forks source link

readme

= 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="

ISO 19115-1:2014 defines the schema required for ...

", @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 => "

ISO 19115-1:2014 defines the schema required for ...

"

=== BibliographicItem references

[source,ruby]

item.shortref item.docidentifier.first => "ISOTC211:2014"

=== XML serialization

[source,ruby]

item.to_xml => "

2022-05-02 
  <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 => "

2022-05-02 
  <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 => "

2022-05-02 
  <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 => " ...

2014-01-01 
  <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" }] => " ...

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 => "

Geographic information International Organization for Standardization .. 
  <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.

== 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.