= 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://img.shields.io/travis/metanorma/relaton-cli/master.svg["Build Status", link="https://travis-ci.org/metanorma/relaton-cli"]
image:https://ci.appveyor.com/api/projects/status/fyy87flpig4q5o2u?svg=true["Appveyor Build Status", link="https://ci.appveyor.com/project/ribose/relaton-cli"]
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/metanorma/relaton.

== Executables

The following executables are included:

=== relaton concatenate

[source,console]
----
$ relaton concatenate Source-Directory Collection-File -t TITLE -g ORGANIZATION
----

Iterates through all the Relaton YAML files in `Source-Directory`, and converts them in-place into Relaton XML.

Iterates through all the Relaton XML files in `Source-Directory` (including those just converted from Relaton YAML),
and outputs to `Collection-File` a `relaton-collection` document containing all the Relaton XML objects read in.

For each Relaton XML file, 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` document.

=== relaton split

[source,console]
----
$ relaton split 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 addional `extension` options to use different extension.

=== relaton fetch

[source,console]
----
$ relaton fetch CODE -t TYPE -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.
* `TYPE` specifies the standards class library to be used, that the identifier is part of; the recognised
values for `TYPE` are `isobib`, `ietfbib`, `iecbib`, `gbbib`.

=== 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-yaml]]
=== 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.

A Relaton Colleciton YAML file contains some initial metadata, and a list of metadata about each bibliographic entry. A Relaton YAML file describing an individual bibliographic entry is limited to metadata specific to that entry. The following illustrates the fields supported:

[source,yaml]
----
htmlstylesheet: ./index-style.css
root:
  title: CalConnect Standards Registry
  author: "CalConnect: The Calendaring and Scheduling Consortium"
  items:
    - technical_committee: TC VCARD
      docidentifier: 18001
      doctype: standard
      title: "Date and time -- Representations for information interchange -- Part 1: Basic rules"
      stage: Published
      revdate: 2018-10-17
      xml: standards/csd-datetime-explict/csd-datetime-explict.xml
      html: standards/csd-datetime-explict/csd-datetime-explict.html
      pdf: standards/csd-datetime-explict/csd-datetime-explict.pdf
      doc: standards/csd-datetime-explict/csd-datetime-explict.doc
      relaton: standards/csd-datetime-explict/cc-18001.xml
    - technical_committee: TC PUBLISH
      docidentifier: 10001
      doctype: governance
      title: "Standardization and publication"
      stage: proposal
      revdate: 2018-10-17
      uri: standards/csd-standardization/csd-standardization.xml
      agency: CalConnect
      language: en
      script: Latn
      edition: 1
----

=== 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 yaml2xml <filename.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 yaml2xmlnew

[source,console]
----
$ relaton yaml2xmlnew <filename.yaml> -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARY
----

Convert a Relaton YAML file (`filename.yaml`) in a new format 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.

A Relaton Colleciton 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 aditional fields. The following illustrates the common fields supported by all flavor gems (see link:https://github.com/relaton/relaton-bib/blob/master/docs/hash.adoc#yaml[Relaton YAML]):

[source,yaml]
----
---
id: ISO/TC211
title:
- type: main
  content: Geographic information
  language: en
  script: Latn
  format: text/plain
- content: Information géographique
  language: fr
  script: Latn
  format: text/plain
link:
- type: src
  content: https://www.iso.org/standard/53798.html
- type: obp
  content: https://www.iso.org/obp/ui/#!iso:std:53798:en
- type: rss
  content: https://www.iso.org/contents/data/standard/05/37/53798.detail.rss
type: standard
docid:
  id: TC211
  type: ISO
docnumber: '123456'
date:
- type: issued
  value: '2014-01-01'
- type: published
  value: '2014-04-01'
- type: accessed
  value: '2015-05-20'
contributor:
- organization:
    name: International Organization for Standardization
    abbreviation: ISO
    subdivision: division
    url: www.iso.org
  role:
    description: Publisher role
    type: publisher
- person:
    name:
      completename:
        content: A. Bierman
        language: en
    affiliation:
      organization:
        name: IETF
        abbreviation: IETF
        identifier:
          type: uri
          id: www.ietf.org
    contact:
    - street:
      - Street
      city: City
      state: State
      country: Country
      postcode: '123456'
    - type: phone
      value: '223322'
  role: author
- organization:
    name: IETF
    abbreviation: IETF
    identifier:
      type: uri
      id: www.ietf.org
  role: publisher
- person:
    name:
      forename:
        content: Forename
        language: en
      initial:
        content: A.
        language: en
      surname:
        content: Bierman
        language: en
      addition:
        content: Addition
        language: en
      prefix:
        content: Prefix
        language: en
    affiliation:
      organization:
        name: IETF
        abbreviation: IETF
      description:
        content: Description
        language: en
    identifier:
      type: uri
      id: www.person.com
    contact:
    - street:
      - Street
      city: City
      state: State
      country: Country
      postcode: '123456'
    - type: phone
      value: '223322'
  role: author
edition: '1'
version:
  revision_date: '2019-04-01'
  draft: draft
biblionote:
  content: note
  type: bibnote
language:
- en
- fr
script: Latn
abstract:
- content: ISO 19115-1:2014 defines the schema required for ...
  language: en
  script: Latn
  format: text/plain
- content: L'ISO 19115-1:2014 définit le schéma requis pour ...
  language: fr
  script: Latn
  format: text/plain
docstatus:
  stage: stage
  substage: substage
  iteration: final
copyright:
  owner:
    name: International Organization for Standardization
    abbreviation: ISO
    url: www.iso.org
  from: '2014'
  to: '2020'
relation:
- type: updates
  bibitem:
    formattedref:
      content: ISO 19115:2003
      format: text/plain
  bib_locality:
    type: updates
    reference_from: Reference form
- type: updates
  bibitem:
    type: standard
    formattedref:
      content: ISO 19115:2003/Cor 1:2006
      format: text/plain
series:
- type: main
  title:
    type: original
    content: ISO/IEC FDIS 10118-3
    language: en
    script: Latn
    format: text/plain
  place: Serie's place
  organization: Serie's organization
  abbreviation: ABVR
  from: '2009-02-01'
  to: '2010-12-20'
  number: serie1234
  partnumber: part5678
- type: alt
  formattedref:
    content: serieref
    language: en
    script: Latn
    format: text/plain
medium:
  form: medium form
  size: medium size
  scale: medium scale
place: bib place
extent:
  type: section
  reference_from: Reference from
  reference_to: Reference to
accesslocation:
- accesslocation1
- accesslocation2
classification:
  value: value
  type: type
validity:
  begins: 2010-10-10 12:21
  ends: 2011-02-03 18:30
  revision: 2011-03-04 09:00
fetched: '2019-08-16'
----

=== relaton xml2yamlnew

[source,console]
----
$ relaton xml2yamlnew <filename.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`) in a new format. 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 yaml2htmlnew

[source,console]
----
$ relaton yaml2xmlnew <filename.yaml> [<stylesheet>] [<liquid-template-dir>]
----

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