File: README — Documentation by YARD 0.9.38

Relaton::Bib is a Ruby gem that implements the BibliographicItem model.

Installation

Add this line to your application’s Gemfile:

gem 'relaton-bib'

And then execute:

$ bundle

Or install it yourself as:

$ gem install relaton-bib

Usage

require 'relaton/bib'
=> true

Create bibliographic item

yaml = File.read 'spec/fixtures/item.yaml'
 => "id: ISO1231994\ntype: standard\nschema_version: 1.0.0\nfetched: \"2022-05-02\"\nformattedref: ISO 123:1994\ntitle..."

item = Relaton::Bib::Item.from_yaml yaml
 => #<Relaton::Bib::ItemData:0x000000012838bfc0 ...

Title

item.title
 => [#<Relaton::Bib::Title:0x00000001270a6810
  @content="Geographic information -- Metadata",
  @format=nil,
  @language="en",
  @locale="en-US",
  @script="Latn",
  @type=nil>,
 #<Relaton::Bib::Title:0x00000001270a5cd0
  @content="Information géographique -- Métadonnées",
  @format=nil,
  @language="fr",
  @locale="fr-FR",
  @script="Latn",
  @type=nil>]

item.title "fr"
 => [#<Relaton::Bib::Title:0x00000001270a5cd0
  @content="Information géographique -- Métadonnées",
  @format=nil,
  @language="fr",
  @locale="fr-FR",
  @script="Latn",
  @type=nil>]

Abstract

item.abstract
 => [#<Relaton::Bib::LocalizedMarkedUpString:0x0000000126c05748
  @content="This is an abstract. <em>This is emphasized</em>",
  @language="en",
  @locale="en-US",
  @script="Latn">]

item.abstract("en")
 => [#<Relaton::Bib::LocalizedMarkedUpString:0x0000000126c05748
  @content="This is an abstract. <em>This is emphasized</em>",
  @language="en",
  @locale="en-US",
  @script="Latn">]

Document identifier

item.docidentifier
 => [#<Relaton::Bib::Docidentifier:0x00000001270a4b00
  @content="ISO 123:1994",
  @language="en",
  @locale="en-US",
  @primary=true,
  @scope="global",
  @script="Latn",
  @type="ISO">,
 #<Relaton::Bib::Docidentifier:0x00000001270a46a0
  @content="10.1007/978-3-319-99155-2_1",
  @language=nil,
  @locale=nil,
  @primary=nil,
  @scope=nil,
  @script=nil,
  @type="DOI">]

XML serialization

item.to_xml
=> "<bibitem id="ISO1231994" type="standard" schema-version="1.0.0">
      <fetched>2022-05-02</fetched>
      <formattedref>ISO 123:1994</formattedref>
      <title language="en" locale="en-US" script="Latn">Geographic information -- Metadata</title>
      <title language="fr" locale="fr-FR" script="Latn">Information géographique -- Métadonnées</title>
      <uri type="src">https://www.iso.org/standard/22722.html</uri>
      <uri type="doi">10.1007/978-3-319-99155-2_1</uri>
      ...
    </bibitem>"

The default root element is bibitem. With argument bibdata: true the XML wrapped with bibdata element.

item.to_xml bibdata: true
=> "<bibdata type="standard" schema-version="1.0.0">
      <fetched>2022-05-02</fetched>
      <formattedref>ISO 123:1994</formattedref>
      <title language="en" locale="en-US" script="Latn">Geographic information -- Metadata</title>
      ...
      <ext schema-version="1.0.0">
        <doctype abbreviation="std">Standard</doctype>
        <subdoctype>Technical Report</subdoctype>
        ...
      </ext>
    </bibdata>"

Adding notes

item.to_xml note: [{ content: "Note", type: "note" }]
=> "<bibitem id="ISO1231994" type="standard" schema-version="1.0.0">
      ...
      <note type="note">Note</note>
      ...
    </bibitem>"

Create bibliographic item form YAML

yaml = File.read 'spec/fixtures/item.yaml'
 => "id: ISO1231994\ntype: standard\nschema_version: 1.0.0\nfetched: \"2022-05-02\"\nformattedref: ISO 123:1994\ntitle..."

Relaton::Bib::Item.from_yaml yaml
 => #<Relaton::Bib::ItemData:0x000000011dc9e118 ...

Create bibliographic item from RFC XML

xml = File.read 'spec/fixtures/rfc.xml'
 => "<reference anchor=\"RFC1\" target=\"10.17487/RFC0001\">\n  <front>\n    <title>Title RFC1</title>\n    <seriesInf..."

Relaton::Bib::Converter::BibXml.to_item xml
 => #<Relaton::Bib::ItemData:0x000000011dc9fc98 ...

Create bibliographic item from XML

xml = File.read 'spec/fixtures/bibitem.xml'
=> "<bibitem id=\"ISO1231994\" type=\"standard\" schema-version=\"1.0.0\">\n  <fetched>2022-05-02</fetched>\n  <forma..."

item = Relaton::Bib::Bibitem.from_xml xml
 => #<Relaton::Bib::ItemData:0x000000011d4b7580 ...

xml = File.read 'spec/fixtures/bibdata.xml'
item = Relaton::Bib::Bibdata.from_xml xml
 => #<Relaton::Bib::ItemData:0x000000011d4daa08 ...

Create bibliographic item from BibTeX (@TODO: add support for BibTeX)

Relaton::Bib::BibtexParser.from_bibtex File.read('spec/fixtures/techreport.bib')
=> {"ISOTC211"=>
  #<Relaton::Bib::Item:0x007fedee0a2ab0
  ...

Export bibliographic item to YAML

item.to_yaml
---
type: standard
schema_version: 1.0.0
fetched: '2022-05-02'
formattedref: ISO 123:1994
...

Export bibliographic item to Hash

item.to_h
=> {"id"=>"ISO1231994",
 "type"=>"standard",
 "schema_version"=>"...",
 "title"=>[...],
 ...}

Export bibliographic item to BibTeX

item.to_bibtex
@misc{doe1994a,
  title = {Geographic information -- Metadata},
  author = {Doe, John},
  edition = {First edition},
  publisher = {International Organization for Standardization},
  year = {1994},
  month = {jan},
  address = {Geneva, Switzerland, Geneva, Geneva},
  pages = {1--10},
  keywords = {information},
  timestamp = {2022-05-02},
  url = {https://www.iso.org/standard/22722.html},
  doi = {10.1007/978-3-319-99155-2_1},
  month_numeric = {1}
}

Export bibliographic item to Citeproc (@TODO: add support for Citeproc)

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 (@TODO: add support for AsciiBib)

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 RFC XML

item.to_rfcxml
<reference anchor="ISO 123:1994" target="https://www.iso.org/standard/22722.html">
  <front>
    <title>Geographic information -- Metadata</title>
    <seriesInfo name="DOI" value="10.1007/978-3-319-99155-2_1"/>
    <seriesInfo name="ISO 123" value="1"/>
    <author initials="J.D." surname="Doe" fullname="Prof. John Doe PhD">
      <organization>International Organization for Standardization</organization>
      <address>
        <postal>
          <street>1, rue de Varembé</street>
          <city>Geneva</city>
          <code>1211</code>
          <country>Switzerland</country>
          <postalLine>1, rue de Varembé,&lt;br/&gt;Geneva, Switzerland, 1211</postalLine>
        </postal>
        <phone>+41 22 749 01 11</phone>
        <email>jdoe@email.org</email>
        <uri>https://orcid.org/0000-0002-1825-0097</uri>
      </address>
    </author>
    <author>
      <organization abbrev="ISO">International Organization for Standardization</organization>
      <address>
        <postal>
          <street>1, rue de Varembé</street>
          <city>Geneva</city>
          <code>1211</code>
          <country>Switzerland</country>
          <postalLine>1, rue de Varembé,&lt;br/&gt;Geneva, Switzerland, 1211</postalLine>
        </postal>
        <phone>+41 22 749 01 11</phone>
        <email>office@iso.org</email>
        <uri>https://www.iso.org</uri>
      </address>
    </author>
    <date day="01" month="January" year="1994"></date>
    <workgroup>Geographic information</workgroup>
    <keyword>information</keyword>
    <abstract>
      <t>This is an abstract. &lt;em&gt;This is emphasized&lt;/em&gt;</t>
    </abstract>
  </front>
</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 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).