= 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` (the short form is `-v`). Use the option to get warnings in the commands output. 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 --no-cache ---- 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 recognized values for `FORMAT` are `xml` (default), yaml, `bibtex`. * `TYPE` is optional and specifies the standards class library to be used, that the identifier is part of. The recognized values for `TYPE` are `3GPP, BIPM, BSI, CC, CCSDS, CEN, CIE, CN, ECMA, IANA, IEC, IEEE, IETF, IHO, ISO, ITU, NIST, OASIS, OGC, OMG, UN, W3C, XSF`. * `RETRIES` is optional, number of network retries (default 1). * `--all-parts` fetch all parts. * `--keep-year` undated reference should return an actual reference with year. * `--no-cache` do not use cache. === 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 the format `FORMAT`. The following datasets are available: * `nist-tech-pubs` - https://raw.githubusercontent.com/usnistgov/NIST-Tech-Pubs/nist-pages/xml/allrecords.xml * `cie-techstreet` - https://www.techstreet.com/cie/searches/31156444 * `calconnect-org` - https://standards.calconnect.org/relaton/index.yaml * `ogc-naming-authority` - https://raw.githubusercontent.com/opengeospatial/NamingAuthority/master/incubation/bibliography/bibliography.json * `ieee-rawbib` - looks for the IEEE dataset in the local `./ieee-rawbib` directory. The dataset could be downloaded from https://github.com/ietf-ribose/ieee-rawbib repository * `w3c-rdf` - http://www.w3.org/2002/01/tr-automation/tr.rdf * `w3c-tr-archive` - looks for the W3C archive dataset in local `./w3c-tr-archive` directory. The dataset could be downloaded from https://github.com/relaton/w3c-tr-archive repository * `iana-registries` - https://github.com/ietf-ribose/iana-registries * `status-smg-3GPP` - updates previously downloaded data if a new archive is available in ftp://www.3gpp.org/Information/Databases/Spec_Status/ * `status-smg-3GPP-force` - download data from the latest archive in ftp://www.3gpp.org/Information/Databases/Spec_Status/ * `ietf-rfcsubseries` - https://www.rfc-editor.org/rfc-index.xml (``, ``, ``) * `ietf-internet-drafts` - looks for the Internet-Drafts dataset in the local `./bibxml-ids` directory. The dataset could be downloaded using `rsync -avcizxL rsync.ietf.org::bibxml-ids ./bibxml-ids` command. * `ietf-rfc-entries` - https://www.rfc-editor.org/rfc-index.xml (``) * `oasis-open` - https://www.oasis-open.org/standards/ * `bipm-data-outcomes` - looks for the BIPM dataset in the local `./bipm-data-outcomes` directory. The dataset could be downloaded from https://github.com/metanorma/bipm-data-outcomes repository * `si-brochure` - looks for the SI-Brochure dataset in the local `./bipm-si-brocure` directory. The dataset could be downloaded from https://github.com/metanorma/bipm-si-brochure repository * `ecma-standards` - https://www.ecma-international.org/publications/standards/ * `itu-r` - https://extranet.itu.int/brdocsearch * `ccsds` - https://public.ccsds.org/Publications/AllPubs.aspx Options: * `DIR` - floder name to store documents (default `./data`). * `FORMAT` - format in which the documents are saved. Possimle formats are: `yaml`, `xml`, `bibxml` (default `yaml`). === 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 [] [] ---- 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` recognizes 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 recognizes attributes of a bibliographic entry (`document`) that follow the naming convention of <>; 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] ----

CC/R 3101

report

CalConnect XLIII -- Position on the European Union daylight-savings timezone change

cancelled
2019-10-17
Relaton XML
HTML
PDF
Word
XML
---- === 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 primary: true 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 primary: true 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 [] [] ---- Render a Relaton YAML file (`filename.yaml`) as an HTML file. The `stylesheet` and `liquid-template-dir` directories are as for <>. === 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 version ---- $ relaton version CLI => 1.15.3 relaton => 1.15.1 relaton-bib => 1.14.11 relaton-iso-bib => 1.14.0 relaton-gb => 1.14.0 relaton-iec => 1.14.3 relaton-ietf => 1.14.3 relaton-iso => 1.15.1 relaton-itu => 1.14.1 relaton-nist => 1.14.3 relaton-ogc => 1.14.1 relaton-calconnect => 1.14.0 relaton-omg => 1.14.0 relaton-un => 1.14.1 relaton-w3c => 1.14.1 relaton-ieee => 1.14.6 relaton-iho => 1.14.2 relaton-bipm => 1.14.6 relaton-ecma => 1.14.1 relaton-cie => 1.14.0 relaton-bsi => 1.14.5 relaton-cen => 1.14.0 relaton-iana => 1.14.1 relaton-3gpp => 1.14.3 relaton-oasis => 1.14.2 relaton-doi => 1.14.3 relaton-jis => 1.14.1 ---- === 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 [relaton-cli] Database is in `/Users/user/.relaton/cache` $ relaton db create cachedb [relaton-cli] 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 [relaton-cli] 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 ... $ relaton db fetch_all 'Procedures for the technical work' 2021-04-01 Procedures for the technical work ... $ relaton db fetch_all -e 3 ... 3 ... $ relaton db fetch_all -e 8 -y 2018 2021-04-01 Principles and rules for the structure and drafting of ISO and IEC documents https://www.iec.ch/members_experts/refdocs/iec/isoiecdir2%7Bed8.0.RLV%7Den.pdf ISO/IEC DIR 2 IEC 2018-05-01 8 ... ---- ==== 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 ----