Relaton CLI (relaton-cli): Relaton Command-line Interface

image:img.shields.io/gem/v/relaton-cli.svg[“Gem Version”, link=“rubygems.org/gems/relaton-cli”] image:github.com/relaton/relaton-cli/workflows/rake/badge.svg[“Build Status”, link=“github.com/relaton/relaton-cli/actions?workflow=rake”] image:codeclimate.com/github/metanorma/relaton-cli/badges/gpa.svg[“Code Climate”, link=“codeclimate.com/github/metanorma/relaton-cli”]

Documentation in development.

Please refer to github.com/relaton/relaton.

Commands

Each command has an option `–verbose` (short form is `-v`). Use the option to get warnings in the commands outpput. The following commands are provided.

relaton concatenate

source,console

$ relaton concatenate Source-Directory Relaton-Collection-File -t TITLE -g ORGANIZATION


Iterates through all the Relaton files (YAML and XML) in `Source-Directory`, and concatenates them into a Relaton Collection file. The extension of the Collection file can be set using the `Relaton-Collection-File` file name (i.e, if it uses an extension of `yaml`, a Relaton YAML file will be created; if `rxl`, a Relaton XML file will be created, or via the `-x [ext]` (or `–extension`) option.

For each Relaton input file in the `Source-Directory`, if a document file with the same base name is identified (i.e. an XML, HTML, PDF or DOC file), a link to that file is inserted.

If the `TITLE` or `ORGANIZATION` options are given, they are added to the `Collection-File` output as the title and author of the `Relaton-Collection-File` document.

relaton split

source,console

$ relaton split Relaton-Collection-File Relaton-File-Directory -x rxl


Splits a `Relaton-Collection-File` into multiple files in the `Relaton-File-Directory`, and it also suports an additional `-x` or `–extension` options to use different extension.

relaton fetch

source,console

$ relaton fetch CODE -t TYPE -f FORMAT -y YEAR -r RETRIES –all-parts –keep-year


Fetch the Relaton XML entry corresponding to the document identifier `CODE`.

  • `YEAR` is optional, and specifies the year of publication of the standard.

  • `FORMAT` is optional, and specifies the output format; the recognised values for `FORMAT` are `xml` (default), yaml, `bibtex`.

  • `TYPE` is optional, specifies the standards class library to be used, that the identifier is part of. The recognised values for `TYPE` are `BIPM`, `CC`, `CIE`, `CN`, `ECMA`, `IEC`, `IEEE`, `IETF`, `IHO`, `ISO`, `ITU`, `NIST`, `OGC`, `OMG`, `UN`, `W3C`.

  • `RETRIES` is optional, number of network retries (default 1).

  • `–all-parts` fetch all parts.

  • `–keep-year` undated reference should return actual reference with year.

relaton fetch-data

source,console

$ relaton fetch-data DATASET -o DIR -f FORMAT


Fetch all the documents from a `DATASET` source and save them to a folder `DIR` in format `FORMAT`.

Foloowing datasets are availabe:

Options:

  • `DIR` - floder name to store documents (default `./data`).

  • `FORMAT` - format in which the documents are saved. Possimle formats are: `yaml`, `xml` (default `yaml`).

source,console

$ relaton extract Metanorma-XML-Directory Relaton-XML-Directory -x EXTENSION


Iterate through all the Metanorma XML files in `Metanorma-XML-Directory`, and extract the `bibdata` element from each. Save the `bibdata` element for each file to `Relaton-XML-Directory`, as the Relaton XML description for that file. If a document identifier is present in `bibdata`, it is used as the name of the file; otherwise, the original file name is used. The filename is suffixed with `EXTENSION`; by default, `.rxl` is used.

[relaton-xml2html]

relaton xml2html

source,console

$ relaton xml2html <relaton-xml> [<stylesheet>] [<html-template-dir>]


Render a Relaton Collection XML as an HTML file. Used to generate an HTML index of standards.

  • `relaton-xml` is the Relaton Collection XML file.

  • `stylesheet` is the CSS stylesheet to be used to style the output. For the CSS styling of each bibliographic element, see below.

  • `html-template-dir` is a directory containing HTML Liquid Template files into which the bibliographic entries are to be inserted.

There are two templates necessary:

** Index template (`index.liquid`)

*** The HTML Template file `_index.liquid` recognises the following parameters: *** `css`: where the CSS stylesheet `stylesheet` is injected *** `title`: the Title of the collection, `./relaton-collection/title` in `relaton-xml` *** `author`: the Author of the collection, `./relaton-collection/contributor[role/@type = 'author']/organization/name` in `relaton-xml` *** `content`: the list of resources generated by the script

** Individual bibliographic entries template (`_document.liquid`)

*** This template recognises attributes of a bibliographic entry (`document`) which follow the naming convention of <<relaton-yaml,Relaton YAML>>; e.g. `document.html` is the HTML URI for the document.

The default stylesheet and templates are given (which also demonstrates the structure) in the `templates` directory.

Sample HTML output for a bibliographic entry:

source,html

<div class=“document”>

<div class="doc-line">
  <div class="doc-identifier">
    <h2>
      <a href="http://calconnect.org/pubdocs/CD0507%20CalDAV%20Use%20Cases%20V1.0.html">CC/R 3101</a>
    </h2>
  </div>
  <div class="doc-type-wrap">
    <div class="doc-type report">report</div>
  </div>
</div>
<div class="doc-title">
  <h3>
    <a href="http://calconnect.org/pubdocs/CD0507%20CalDAV%20Use%20Cases%20V1.0.html">CalConnect XLIII -- Position on the European Union daylight-savings timezone change</a>
  </h3>
</div>
<div class="doc-info cancelled">
  <div class="doc-stage cancelled">cancelled</div>
  <div class="doc-dates">
    <div class="doc-updated">2019-10-17</div>
  </div>
</div>
<div class="doc-bib">
  <div class="doc-bib-relaton">
    <a href="csd/cc-r-3101.xml">Relaton XML</a>
  </div>
</div>
<div class="doc-access">
  <div class="doc-access-button-html">
    <a href="http://calconnect.org/pubdocs/CD0507%20CalDAV%20Use%20Cases%20V1.0.html">HTML</a>
  </div>
  <div class="doc-access-button-pdf">
    <a href="http://calconnect.org/pubdocs/CD0507%20CalDAV%20Use%20Cases%20V1.0.pdf">PDF</a>
  </div>
  <div class="doc-access-button-doc">
    <a href="http://calconnect.org/pubdocs/CD0507%20CalDAV%20Use%20Cases%20V1.0.doc">Word</a>
  </div>
  <div class="doc-access-button-xml">
    <a href="http://calconnect.org/pubdocs/CD0507%20CalDAV%20Use%20Cases%20V1.0.xml">XML</a>
  </div>
</div>

</div>


relaton yaml2xml

source,console

$ relaton yaml2xml YAML -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARY


Convert a Relaton YAML file (`filename.yaml`) into a Relaton XML file (`filename.xml`). If the Relaton YAML file specifies multiple bibliograph items, and `OUTPUT-DIRECTORY` is nominated, also convert the file into a list of Relaton XML files for each entry, stored in that directory. The document identifier is used as the name of each Relaton XML file; the Relaton XML filename is suffixed with `RELATON_EXTENSION` (default `.rxl`) and prefixed with `PREFIX` (default empty). Any libraries that need to be required for the conversion are specified in `LIBRARY` as a space-delimited list.

[relaton-yaml]

A Relaton Collection YAML file contains some initial metadata, and a list of metadata about each bibliographic entry:

source,yaml

root:

author: The Calendaring and Scheduling Consortium
title: CalConnect Standards Registry
items:
  - technical_committee: PUBLISH
    docid:
      type: CC
      id: CC 36000
    type: standard
    title:
      type: main
      content: Standardization documents -- Vocabulary
    docstatus:
      stage: proposal
    date:
      type: issued
      value:  2018-10-25
  - technical_committee: DATETIME
    docid:
      type: CC
      id: CC 34000
    type: standard
    title:
      type: main
      content: Date and time -- Concepts and vocabulary
    docstatus:
      stage: proposal
    date:
      type: issued
      value: 2018-10-25

A Relaton YAML file describing an individual bibliographic entry is limited to metadata specific to that entry. Flavor gems have additional fields. The https://github.com/relaton/relaton-bib/blob/master/docs/hash.adoc#yaml[Relaton YAML] illustrates the common fields supported by all flavor gems.

relaton xml2yaml

source,console

$ relaton xml2yaml XML -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARY


Convert a Relaton XML file (`filename.xml` or `filename.rxl`) into a Relaton YAML file (`filename.yaml`). If the Relaton XML file is a collection, and `OUTPUT-DIRECTORY` is nominated, also convert the file into a list of Relaton YAML files for each entry, stored in that directory. The document identifier is used as the name of each Relaton XML file; the Relaton XML filename is suffixed with `RELATON_EXTENSION` (default `.yaml`) and prefixed with `PREFIX` (default empty). Any libraries that need to be required for the conversion are specified in `LIBRARY` as a space-delimited list.

relaton yaml2html

source,console

$ relaton yaml2html YAML [<stylesheet>] [<liquid-template-dir>]


Render a Relaton YAML file (`filename.yaml`) as an HTML file. The `stylesheet` and `liquid-template-dir` directories are as for <<relaton-xml2html,relaton xml2html>>.

relaton convert

source,conxole

$ relaton convert XML -f FORMAT -o OUTPUT-FILE


Convert a Relaton XML document into YAML, AsciiBib, or BibTex format. Allowed -f or –format options are yaml, asciibib, bibtex. If the option -o or –output is omitted then a new file will be created in the folder where the original file is, with the same name but another appropriated extension.

relaton collection

The `relaton collection` is a set of subcommands for collections manipulations.

relaton collection create


$ relaton collection create COLLECTION -d DIRECTORY –author AUTHOR –title TITLE –doctype DOCTYPE


Create new empty collection with name `COLLECTION`.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

  • `AUTHOR`, `TITLE`, and `DOCTYPE` are optional.

relaton collection info


$ relaton collection info COLLECTION -d DIRECTORY


Show information about `COLLECTION` (number of items, file size of collection, last updated, name, metadata).

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

relaton collection list


$ relaton collection list -d DIRECTORY -e


List all collections.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

  • When parametr `-e` is defined the id of each entry id will be listed.

relaton collection get


$ relaton collection get CODE -c COLLECTION -d DIRECTORY -f FORMAT -o FILE


Get a document matched to `CODE` from `COLLECTION`.

  • `COLLECTION` is optional name of collection. If undefined then fetch the first match across all collections in `DIRECTORY`.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

  • `FORMAT` is optional. If udefined then print documern in a human-readable form. Allowed values are `abb` (AsciiBib) or `xml` (XML).

  • `FILE` is optional. When it's defined then save document with given file name. File's extension defines format of the file. Possible extensions are `abb` (AsciiBib) or `xml` (XML).

relaton collection find


$ relaton collection find TEXT -c COLLECTION -d DIRECTORY


Full-text search through a collection or all collections.

  • `COLLECTION` is optional name of collection. If udefined then search across all collections.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

relaton collection fetch


$ relaton collection fetch CODE -t TYPE -y YEAR -c COLLECTION -d DIRECTORY


Fetch the Relaton XML entry corresponding to the document identifier `CODE` and save it into `COLLECTION`.

  • `TYPE` specifies the standards class library to be used, that the identifier is part of. The recognised values for `TYPE` are `BIPM`, `CC`, `CN`, `IEC`, `IEEE`, `IETF`, `IHO`, `ISO`, `ITU`, `NIST`, `OGC`, `OMG`, `UN`, `W3C`.

  • `YEAR` is optional, and specifies the year of publication of the standard.

  • `COLLECTION` is a name of collection.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

relaton collection export


$ relaton collection export COLLECTION -d DIRECTORY


Export `COLLECTION` into XML file.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

relaton collection import


$ relaton collection import FILE -c COLLECTION -d DIRECTORY


Import document or collection from XML `FILE` into `COLLECTION`.

  • `COLLECTION` is optional. If collection doesn't exist then it will be created.

  • `DIRECTORY` is optional, and specifies path to a directory with collections. Default is `$HOME/.relaton/collections`.

Dadabase manipulation

Create database


$ relaton db create DIR


Creates a new database in a directory `DIR` (optional, deafult is `/home/USER/.relaton/dbpath`). In case the target directory exists it will be used as a database.


$ relaton db create Database is in “/Users/user/.relaton/cache”

$ relaton db create cachedb Database is in “/Users/user/RubyProjects/relaton-cli/cachedb”


Move database


$ relaton db mv DIR


Move database to another place `DIR`.


$ relaton db mv cache_dir Database is moved to “/Users/user/RubyProjects/relaton-cli/cache_dir”


Clear database

Delete all entries from a chache DB.


$ relaton db clear


Fetch from database


$ relaton db fetch -t TYPE -f FORMAT -y YEAR


Fetch an entry from a database. See [relaton fetch](relaton-fetch) for the arguments explanation.

Fetch all

Fetch all entries from a chache DB.


$ relaton db fetch_all TEXT -e EDITION -y YEAR -f FORMAT


  • `TEXT` (optional) search for a certan string

  • `EDITION` (optional) filter documets with a certain edition

  • `YEAR` (optional) filter documents by a year

  • `FORMAT` (optional) specify the output format. Recognised values are `xml` (default), yaml, `bibtex`.


$ relaton db fetch_all <bibitem id=“ISO/IECDIR1” type=“international-standard”> …

$ relaton db fetch_all 'Procedures for the technical work' <bibitem id=“ISO/IECDIR1” type=“international-standard”>

<fetched>2021-04-01</fetched>
<title type="title-main" format="text/plain" language="en" script="Latn">Procedures for the technical work</title>

$ relaton db fetch_all -e 3

<bibitem id=“ISO2146-2010” type=“standard”> … <edition>3</edition> …

$ relaton db fetch_all -e 8 -y 2018 <bibitem id=“ISO/IECDIR2IEC” type=“international-standard”>

<fetched>2021-04-01</fetched>
<title type="title-main" format="text/plain" language="en" script="Latn">Principles and rules for the structure and drafting of ISO and IEC documents</title>
<uri type="obp">https://www.iec.ch/members_experts/refdocs/iec/isoiecdir2%7Bed8.0.RLV%7Den.pdf</uri>
<docidentifier type="ISO">ISO/IEC DIR 2 IEC</docidentifier>
<date type="published">
  <on>2018-05-01</on>
</date>
<edition>8</edition>


Get document type


$ relaton db doctype REF


Takes a reference `REF` and retuern a document type.


$ relaton db doctype 'CN(GB/T 1.1)' Chinese Standard GB/T 1.1