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 aRelaton
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`, aRelaton
YAML file will be created; if `rxl`, aRelaton
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 aRelaton
XML file (`filename.xml`). If theRelaton
YAML file specifies multiple bibliograph items, and `OUTPUT-DIRECTORY` is nominated, also convert the file into a list ofRelaton
XML files for each entry, stored in that directory. The document identifier is used as the name of eachRelaton
XML file; theRelaton
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 aRelaton
YAML file (`filename.yaml`). If theRelaton
XML file is a collection, and `OUTPUT-DIRECTORY` is nominated, also convert the file into a list ofRelaton
YAML files for each entry, stored in that directory. The document identifier is used as the name of eachRelaton
XML file; theRelaton
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
-
-
-
-