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