= 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
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
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
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, CCTF, CCDS, CGPM, CIPM, JCRB, JCGM, BSI, BS, PD, CC, CCSDS, CEN, EN, ENV, CWA, HD, CR, CIE, DOI, ECMA, ETSI, CN, GB, GB/T, GB/Z, IANA, IEC, CISPR, IEV, IEEE, ANSI, NACE, AIEE, ASA, IRE, IETF, RFC, BCP, FYI, STD, I-D, IHO, ISBN, ISO, ISO/IEC, ITU, JIS, TR, NIST, NBS, NISTGCR, ITL Bulletin, JPCRD, NISTIR, CSRC, FIPS, OASIS, OGC, OMG, UN, W3C, XEP, PLATEAU.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
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://github.com/usnistgov/NIST-Tech-Pubs/releases/download/May2024/allrecords-MODS.xmlcie-techstreet - https://www.techstreet.com/cie/searches/31156444calconnect-org - https://standards.calconnect.org/relaton/index.yamlogc-naming-authority - https://raw.githubusercontent.com/opengeospatial/NamingAuthority/master/incubation/bibliography/bibliography.jsonieee-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 repositoryw3c-rdf - http://www.w3.org/2002/01/tr-automation/tr.rdfw3c-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 repositoryiana-registries - https://github.com/ietf-ribose/iana-registriesstatus-smg-3GPP - updates previously downloaded data if a new archive is available in ftp://www.3gpp.org/Information/Databases/status-smg-3GPP-force - download data from the latest archive in ftp://www.3gpp.org/Information/Databases/ietf-rfcsubseries - https://www.rfc-editor.org/rfc-index.xml (<bcp-entry>, <fyi-entry>, <std-entry>)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 (<rfc-entry>)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 repositorysi-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 repositoryecma-standards - https://www.ecma-international.org/publications/standards/itu-r - https://extranet.itu.int/brdocsearchccsds - https://public.ccsds.org/Publications/AllPubs.aspxetsi-csv - https://www.etsi.org/plateau-handbooks - https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/handbooks.jsonplateau-technical-reports - https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/technical-reports.jsonjis-webdesk - https://webdesk.jsa.or.jp/books/W11M0270Options:
DIR - folder name to store documents (default ./data).FORMAT - format in which the documents are saved. Possible formats are: yaml, xml, bibxml (default yaml).=== relaton extract
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
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 <<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:
=== relaton yaml2xml
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:
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
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
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
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 collection manipulations.
==== relaton collection create
Create a new empty collection with the name COLLECTION.
DIRECTORY - optional, and specifies a path to a directory with collections. The default value is $HOME/.relaton/collections.AUTHOR, TITLE, and DOCTYPE are optional.==== relaton collection info
Show information about COLLECTION (number of items, file size of collection, last updated, name, metadata).
DIRECTORY is optional, and specifies the path to a directory with collections. The default value is $HOME/.relaton/collections.==== relaton collection list
List all collections.
DIRECTORY - optional, and specifies the path to a directory with collections. The default value is $HOME/.relaton/collections.-e is defined the id of each entry id will be listed.==== relaton collection get
Get a document matched to CODE from COLLECTION.
COLLECTION - optional name of a collection. If undefined then fetch the first match across all collections in DIRECTORY.DIRECTORY - optional, and specifies a path to a directory with collections. The default value is $HOME/.relaton/collections.FORMAT - optional. If undefined then print a document in a human-readable form. Allowed values are abb (AsciiBib) or xml (XML).FILE is optional. When it's defined then save a document with the given file name. The file's extension defines the format of the file. Possible extensions are abb (AsciiBib) or xml (XML).==== relaton collection find
Full-text search through a collection or all collections.
COLLECTION - optional name of a collection. If undefined then search across all collections.DIRECTORY - optional, and specifies a path to a directory with collections. The default value is $HOME/.relaton/collections.==== relaton collection fetch
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 recognized values for TYPE are: 3GPP, BIPM, CCTF, CCDS, CGPM, CIPM, JCRB, JCGM, BSI, BS, PD, CC, CCSDS, CEN, EN, ENV, CWA, HD, CR, CIE, DOI, ECMA, ETSI, CN, GB, GB/T, GB/Z, IANA, IEC, CISPR, IEV, IEEE, ANSI, NACE, AIEE, ASA, IRE, IETF, RFC, BCP, FYI, STD, I-D, IHO, ISBN, ISO, ISO/IEC, ITU, JIS, TR, NIST, NBS, NISTGCR, ITL Bulletin, JPCRD, NISTIR, CSRC, FIPS, OASIS, OGC, OMG, UN, W3C, XEP.YEAR is optional, and specifies the year of publication of the standard.COLLECTION - a name of a collection.DIRECTORY - optional, and specifies a path to a directory with collections. The default value is $HOME/.relaton/collections.==== relaton collection export
Export COLLECTION into an XML file.
DIRECTORY - optional, and specifies a path to a directory with collections. The default value is $HOME/.relaton/collections.==== relaton collection import
Import document or collection from XML FILE into COLLECTION.
COLLECTION - optional. If a collection doesn't exist then it will be created.DIRECTORY - optional, and specifies a path to a directory with collections. The default value is $HOME/.relaton/collections.=== Dadabase manipulation
==== Create database
Creates a new database in a directory DIR (optional, the default value 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
/Users/user/RubyProjects/relaton-cli/cachedb==== Move database
Move a database to another place DIR.
/Users/user/RubyProjects/relaton-cli/cache_dir==== Clear database
Delete all entries from a cache DB.
==== Fetch from database
Fetch an entry from a database. See relaton fetch for the explanation of the arguments.
==== Fetch all
Fetch all entries from a cache DB.
TEXT (optional) search for a certain stringEDITION (optional) filter documents with a certain editionYEAR (optional) filter documents by a yearFORMAT (optional) specifies the output format. Recognized 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
Takes a reference REF and returns a document type.
FAQs
Unknown package
We found that relaton-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.