= 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/ubuntu/badge.svg["Build Status", link="https://github.com/relaton/relaton-cli/actions?workflow=ubuntu"]
image:https://github.com/relaton/relaton-cli/workflows/macos/badge.svg["Build Status", link="https://github.com/relaton/relaton-cli/actions?workflow=macos"]
image:https://github.com/relaton/relaton-cli/workflows/windows/badge.svg["Build Status", link="https://github.com/relaton/relaton-cli/actions?workflow=windows"]
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

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

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), `bibtex`.
* `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`.

=== relaton extract

[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`.