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

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

Documentation in development.

Please refer to https://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:

* `nist-tech-pubs` - https://raw.githubusercontent.com/usnistgov/NIST-Tech-Pubs/nist-pages/xml/allrecords.xml

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 link: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
----