Relaton Command-line Interface (CLI)

Relaton Command-line Interface

GitHub

The relaton command-line interface (CLI) provides a set of commands for working with Relaton files.

The commands are designed to be used in a Unix-like environment.

The relaton command is installed as a Ruby gem. To install the gem, run:

$ gem install relaton-cli

The relaton help command provides a list of available commands.

$ relaton help
relaton help
Commands:
  relaton collection SUBCOMMAND                                         # Collection manipulations
  relaton concatenate SOURCE-DIR COLLECTION-FILE                        # Concatenate entries in DIRECTORY (containing Relaton-XML or YAML) into a Relaton Collection
  relaton convert XML -f, --format=FORMAT                               # Convert Relaton XML document
  relaton db SUBCOMMAND                                                 # Cache DB manipulation
  relaton extract Metanorma-XML-File / Directory Relaton-XML-Directory  # Extract Relaton XML from Metanorma XML file / directory
  relaton fetch CODE                                                    # Fetch Relaton XML for Standard identifier CODE
  relaton fetch-data SOURCE                                             # Fetch all the documents from a source
  relaton help [COMMAND]                                                # Describe available commands or one specific command
  relaton split Relaton-Collection-File Relaton-XML-Directory           # Split a Relaton Collection into multiple files
  relaton version                                                       # Show Relaton version
  relaton xml2html RELATON-INDEX-XML                                    # Convert Relaton Collection XML into HTML
  relaton xml2yaml XML                                                  # Convert Relaton XML into Relaton Bibdata / Bibcollection YAML (and separate files)
  relaton yaml2html RELATON-INDEX-YAML                                  # Concatenate Relaton Collection YAML into HTML
  relaton yaml2xml YAML                                                 # Convert Relaton YAML into Relaton Collection XML or separate files

Options:
  -v, [--verbose], [--no-verbose], [--skip-verbose]  # Output warnings

Command listing

The following commands are provided.

relaton collection: Collection manipulations.
relaton concatenate: Concatenate entries in a directory (containing Relaton-XML or YAML) into a Relaton Collection.
relaton convert: Convert Relaton XML document.
relaton db: Cache DB manipulation.
relaton extract: Extract Relaton XML from Metanorma XML file / directory.
relaton fetch: Fetch Relaton XML for Standard identifier CODE.
relaton fetch-data: Fetch all the documents from a source.
relaton version: Show Relaton version.
relaton xml2html: Convert Relaton Collection XML into HTML.
relaton xml2yaml: Convert Relaton XML into Relaton Bibdata / Bibcollection YAML (and separate files).
relaton yaml2html: Concatenate Relaton Collection YAML into HTML.
relaton yaml2xml: Convert Relaton YAML into Relaton Collection XML or separate files.

relaton collection

The relaton collection command provides a set of subcommands for working with Relaton collections.

$ relaton collection help
relaton help collection
Commands:
  relaton collection create COLLECTION                                       # Create collection
  relaton collection export COLLECTION                                       # Export collection into XML file
  relaton collection fetch CODE -c, --collection=COLLECTION -t, --type=TYPE  # Fetch a document and store it into a collection
  relaton collection find TEXT                                               # Full-text search
  relaton collection get CODE                                                # Fetch document from collection by ID
  relaton collection help [COMMAND]                                          # Describe subcommands or one specific subcommand
  relaton collection import FILE -c, --collection=COLLECTION                 # Import document or collection from an XML file into another collection
  relaton collection info COLLECTION                                         # View collection information
  relaton collection list                                                    # List collections

Options:
  -v, [--verbose], [--no-verbose], [--skip-verbose]  # Output warnings

The following subcommands are provided.

relaton collection create COLLECTION: Create a new collection.
relaton collection export COLLECTION: Export a collection into an XML file.
relaton collection fetch CODE: Fetch a document by document identifier and store it in a collection.
relaton collection find TEXT: Full-text search.
relaton collection get CODE: Fetch a document from a collection by document identifier.
relaton collection import FILE: Import a document or collection from an XML file into another collection.
relaton collection info COLLECTION: View information about a collection.
relaton collection list: List collections.

relaton collection create

Creates a new collection with the name COLLECTION_NAME.

$ relaton collection create COLLECTION_NAME

$ relaton collection create my_bib
$ relaton collection list
my_bib

relaton collection export

Exports the collection COLLECTION_NAME into an XML file.

$ relaton collection export COLLECTION_NAME

$ relaton collection export my_bib
$ cat my_bib.xml
<relaton-collection xmlns="https://open.ribose.com/relaton-xml"></relaton-collection>

relaton collection fetch

Fetches a document by document identifier CODE and stores it in the collection COLLECTION_NAME.

The type argument is necessary.

$ relaton collection fetch CODE -c COLLECTION_NAME -t TYPE

$ relaton collection fetch "ISO 8601-1:2019" -c my_bib -t category_one
$ relaton collection list
my_bib
$ relaton collection get "ISO 8601-1:2019" -c my_bib
Document identifier: ISO 8601-1:2019
Title: Date and time
Status: #<RelatonBib::DocumentStatus::Stage:0x000000011fa67cf8>
Date published: 2019-02
$ relaton collection export my_bib
$ cat my_bib.xml
<relaton-collection xmlns="https://open.ribose.com/relaton-xml">
  <bibitem type="standard">
    <docidentifier type="ISO">ISO 8601-1:2019</docidentifier>
    <title language="en" format="text/plain">Date and time — Representations for information interchange</title>
    <date type="published">
      <on>2019-12-15</on>
    </date>
    <contributor>
      <role type="publisher"/>
      <organization>
        <name>International Organization for Standardization</name>
      </organization>
    </contributor>
  </bibitem>
</relaton-collection>

relaton collection find

Performs a full-text search for TEXT in the collection.

$ relaton collection find TEXT

relaton collection get

Fetches a document by document identifier CODE from the collection COLLECTION_NAME.

$ relaton collection get CODE -c COLLECTION_NAME

relaton collection import

Imports a document or collection from an XML file into another collection.

$ relaton collection import FILE -c COLLECTION_NAME

relaton collection info

Displays information about the collection COLLECTION_NAME.

$ relaton collection info COLLECTION_NAME

relaton collection info my_bib
Collection: my_bib
Last updated: 2025-01-28 14:11:07 +0800
File size: 6729
2024-10-31
2019-02
Number of items: 1
Author:
Title:

relaton collection list

Lists all collections.

$ relaton collection list

$ relaton collection list
my_bib

relaton concatenate

$ 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 convert

Converts a Relaton XML file into a different format. The FORMAT argument specifies the format to which the file is to be converted. The supported formats are yaml and rxl.

$ relaton convert Relaton-XML-File -f FORMAT

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 split Relaton-Collection-File Relaton-File-Directory -x rxl

relaton fetch

Fetch the Relaton XML entry corresponding to the document identifier CODE.

$ relaton fetch CODE -t TYPE -y YEAR

CODE

starts with one of the recognized prefixes. Prefix specifies the type of the document and the standard class library. The following prefixes are recognized:

CN: Chinese GB standards
IEC: International Electrotechnical Commission
RFC: Internet Engineering Task Force (IETF)
ISO: International Organization for Standardization
ITU: International Telecommunication Union
NIST: National Institute of Standards and Technology
OGC: Open Geospatial Consortium
CC: Calendaring and Scheduling Consortium
OMG: Object Management Group
UN: United Nations
W3C: World Wide Web Consortium
IEEE: Institute of Electrical and Electronics Engineers
IHO: International Hydrographic Organization
BIPM: Bureau International des Poids et Mesures
ECMA: European Computer Manufacturers Association
CIE: International Commission on Illumination
BSI, BS, PD: British Standards Institution
CEN: European Committee for Standardization

YEAR

optional. Specifies the year of publication of the standard.

TYPE

optional. Specifies the standards class library to be used, that the identifier is part of. The recognized values for TYPE are: BIPM, BSI, CC (CalConnect), CEN, CIE, CN (Chinese GB standards), ECMA, IEC, IEEE, IETF, IHO, ISO, ITU, NIST, OGC, OMG, UN, W3C.

relaton fetch-data

Fetch all the documents from a source.

relaton extract

$ 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 <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; 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:

<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

Convert a Relaton YAML file (filename.yaml) into a Relaton XML file (filename.xml).

$ relaton yaml2xml YAML -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARY

If the Relaton YAML file specifies multiple bibliographic 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 Collection YAML file contains some initial metadata, and a list of metadata about each bibliographic entry:

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 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 xml2yaml XML -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARY

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 yaml2html YAML [<stylesheet>] [<liquid-template-dir>]