npm:@citation-js/plugin-software-formats

README

Install

npm

npm install @citation-js/plugin-software-formats

Browser

Make a build with @citation-js/plugin-software-formats on the build tool!

Use

require('@citation-js/plugin-software-formats')

Formats

Formats and other features added by this plugin.

Input

The CSL standard has no type for software, so (by convention) book is used instead.

YAML

This plugin adds support for YAML files. This is done with the yamljs package.

CFF

This plugin adds support for Citation File Format (CFF) files, both in YAML and in JSON form.

# Example from https://github.com/citation-file-format/citation-file-format#example

cff-version: 1.1.0
message: If you use this software, please cite it as below.
authors:
  - family-names: Druskat
    given-names: Stephan
    orcid: https://orcid.org/0000-0003-4925-7248
title: My Research Tool
version: 1.0.4
doi: 10.5281/zenodo.1234
date-released: 2017-12-18

becomes

{
  author: [ { family: 'Druskat', given: 'Stephan' } ],
  issued: { 'date-parts': [ [2017, 12, 18] ] },
  DOI: '10.5281/zenodo.1234',
  title: 'My Research Tool',
  version: '1.0.4',
  type: 'book',
  _cff_mainReference: true
}

GitHub

This plugin can retrieve bibliographical data from the GitHub API. Note, however, that said API practices rate-limiting, namely 60 unauthorized requests per hours. Also, because the API is limited, a single source can take ~10 API requests. With authorized requests, you can make up to 5000 requests per hour. To let Citation.js make authorized requests, you can set an OAuth token. To get an OAuth token from your GitHub account, see this guide. You don't need to select any additional scopes. Citation.js won't do anything else with this OAuth token.

Cite.plugins.config.get('@github').setApiToken(OAUTH_TOKEN)

Cite.async('https://github.com/citation-js/plugin-software-formats')

{
  type: 'book',
  'title-short': 'plugin-software-formats',
  title: 'citation-js/plugin-software-formats',
  abstract: 'Collection of software-related input and output formats for Citation.js',
  URL: 'https://github.com/citation-js/plugin-software-formats',
  issued: { 'date-parts': [ [2020, 30, 21] ] },
  author: [ { given: 'Lars', family: 'Willighagen' } ],
  version: 'v0.4.2'
}

npm

This plugin can retrieve bibliographical data from the main npm registry. Note that the author property is limited to a single author, since the maintainers data only has usernames and there is no public API to retrieve the associated full name.

Cite.async('https://www.npmjs.com/package/@citation-js/plugin-software-formats')

{
  type: 'book',
  title: '@citation-js/plugin-software-formats',
  version: '0.4.2',
  issued: { 'date-parts': [ [2020, 30, 21] ] },
  abstract: 'Collection of software-related input and output formats for Citation.js',
  URL: 'https://github.com/larsgw/citation.js-plugin-software-formats#readme',
  author: [ { given: 'Lars', family: 'Willighagen' } ]
}

Output

CFF

This plugin supports CFF output, both in YAML and in JSON form. If you pass multiple references the first counts as the main reference, while the rest are added in the references list. To specify a different entry as the main reference, pass the entry ID in the main options:

Cite(/* ... */).format('cff', {
  main: '...'
})

Alternatively, the entry can have _cff_mainReference set to true, but that is mainly used for round-tripping.

You can also specify the message, a mandatory part of every CFF file. By default, the message is:

Please cite the following works when using this software.

To change it, pass a string to the message option when formatting:

Cite(/* ... */).format('cff', {
  message: 'If you use this software, please cite it as below.'
})

License

The code and most other contents in this repository is licensed MIT. test/cache/cache.json contains data about MIT-licensed repositories and packages from GitHub and npm respectively. test/cff.js contains code examples from the CFF repository, licensed under CC-BY-4.0.

Usage no npm install needed!