gem-hunter
Language: Ruby
CLI for the Relaton bibliographic information repository
Each command supports a --verbose (short form -v) option to include
warnings in the output.
$ relaton fetch CODE -t TYPE -f FORMAT -y YEAR -r RETRIES --all-parts --keep-year --no-cache --publication-date-before DATE --publication-date-after DATEFetch the Relaton XML entry corresponding to the document identifier CODE.
TYPE is optional and specifies the standards class library to use. 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.
FORMAT is optional. Recognized values are xml (default), yaml, bibtex.
YEAR is optional and specifies the year of publication.
RETRIES is optional, number of network retries (default 1).
--all-parts fetch all parts of the standard.
--keep-year undated reference should return an actual reference with year.
--no-cache do not use cache.
--publication-date-before DATE fetch only documents published before the specified date. Accepted formats: YYYY, YYYY-MM, YYYY-MM-DD.
--publication-date-after DATE fetch only documents published after the specified date. Accepted formats: YYYY, YYYY-MM, YYYY-MM-DD.
$ relaton fetch-data DATASET -o DIR -f FORMATFetch all documents from a DATASET source and save them to folder DIR in format FORMAT.
The following datasets are available:
nist-tech-pubs - https://github.com/usnistgov/NIST-Tech-Pubs/releases/download/May2024/allrecords-MODS.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 can be downloaded from https://github.com/ietf-ribose/ieee-rawbib
w3c-tr-archive - looks for the W3C archive dataset in local ./w3c-tr-archive directory. The dataset can be downloaded from https://github.com/relaton/w3c-tr-archive
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/
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 can be downloaded using rsync -avcizxL rsync.ietf.org::bibxml-ids ./bibxml-ids.
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 can be downloaded from https://github.com/metanorma/bipm-data-outcomes
si-brochure - looks for the SI-Brochure dataset in the local ./bipm-si-brochure directory. The dataset can be downloaded from https://github.com/metanorma/bipm-si-brochure
ecma-standards - https://www.ecma-international.org/publications/standards/
etsi-csv - https://www.etsi.org/
plateau-handbooks - https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/handbooks.json
plateau-technical-reports - https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/technical-reports.json
jis-webdesk - https://webdesk.jsa.or.jp/books/W11M0270
Options:
DIR - folder name to store documents (default ./data).
FORMAT - output format: yaml (default), xml, bibxml.
$ relaton extract Metanorma-XML-Directory Relaton-XML-Directory -x EXTENSIONIterate through all Metanorma XML files in Metanorma-XML-Directory and extract the bibdata element from each. Save the bibdata element 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 filename; otherwise, the original filename is used. The filename is suffixed with EXTENSION (default .rxl).
$ relaton concatenate Source-Directory Relaton-Collection-File -t TITLE -g ORGANIZATIONIterate through all Relaton files (YAML and XML) in Source-Directory and concatenate them into a Relaton Collection file. The extension of the Collection file can be set via the filename (e.g., .yaml for YAML, .rxl for XML) or using the -x (--extension) option.
For each Relaton input file in Source-Directory, if a document file with the same base name is identified (XML, HTML, PDF, or DOC), a link to that file is inserted.
If TITLE or ORGANIZATION options are given, they are added to the output as the title and author of the collection.
$ relaton split Relaton-Collection-File Relaton-File-Directory -x rxlSplit a Relaton-Collection-File into multiple files in Relaton-File-Directory. Supports the -x (--extension) option to set the file extension.
$ relaton convert XML -f FORMAT -o OUTPUT-FILEConvert a Relaton XML document into YAML, AsciiBib, or BibTeX format. Allowed --format values are yaml, asciibib, bibtex. If --output is omitted, a new file is created in the same folder with the appropriate extension.
$ relaton yaml2xml YAML -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARYConvert a Relaton YAML file into Relaton Collection XML or separate files. If the YAML file specifies multiple bibliographic items and OUTPUT-DIRECTORY is given, also convert into individual Relaton XML files per entry. The document identifier is used as the filename, suffixed with RELATON_EXTENSION (default .rxl) and prefixed with PREFIX (default empty). Libraries required for conversion are specified in LIBRARY as a space-delimited list.
A Relaton Collection YAML file contains initial metadata and a list of bibliographic entries:
root: title: CalConnect Standards Registry author: The Calendaring and Scheduling Consortium items: - id: CC36000 type: standard title: - content: Standardization documents -- Vocabulary docidentifier: - type: CC content: CC 36000 primary: true date: - type: issued at: '2018-10-25' status: stage: content: proposal - id: CC34000 type: standard title: - content: Date and time -- Concepts and vocabulary docidentifier: - type: CC content: CC 34000 primary: true date: - type: issued at: '2018-10-25' status: stage: content: proposal
A Relaton YAML file describing an individual bibliographic entry is limited to metadata specific to that entry. The Relaton YAML illustrates the common fields supported by all flavor gems.
$ relaton xml2yaml XML -o OUTPUT-DIRECTORY -x RELATON_EXTENSION -p PREFIX -r LIBRARYConvert a Relaton XML file into Relaton YAML. If the XML file is a collection and OUTPUT-DIRECTORY is given, also produce individual YAML files per entry. The document identifier is used as the filename, suffixed with RELATON_EXTENSION (default .yaml) and prefixed with PREFIX (default empty). Libraries required for conversion are specified in LIBRARY as a space-delimited list.
$ 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 style the output.
html-template-dir is a directory containing HTML Liquid Template files. Two templates are required:
Index template (_index.liquid) — recognizes the following parameters:
css: the CSS stylesheet content
title: the collection title from ./relaton-collection/title
author: the collection author from ./relaton-collection/contributor[role/@type = 'author']/organization/name
content: the list of resources generated by the script
Individual entry template (_document.liquid) — recognizes attributes of a bibliographic entry (document) following the naming convention of Relaton YAML; e.g. document.html is the HTML URI for the document.
The default stylesheet and templates are provided in the templates directory.
$ relaton yaml2html YAML [<stylesheet>] [<liquid-template-dir>]Render a Relaton YAML file as an HTML file. The stylesheet and liquid-template-dir parameters are as for relaton xml2html.
$ relaton versionDisplay version information for the CLI and all installed Relaton libraries.
The relaton collection command provides subcommands for collection manipulation.
$ relaton collection create COLLECTION -d DIRECTORY --author AUTHOR --title TITLE --doctype DOCTYPE
Create a new empty collection with the name COLLECTION.
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
AUTHOR, TITLE, and DOCTYPE are optional metadata.
$ relaton collection info COLLECTION -d DIRECTORY
Show information about COLLECTION (number of items, file size, last updated, name, metadata).
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
$ relaton collection list -d DIRECTORY -e
List all collections.
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
-e - when set, list the document ID of each entry.
$ relaton collection get CODE -c COLLECTION -d DIRECTORY -f FORMAT -o FILE
Get a document matching CODE from COLLECTION.
COLLECTION - optional name of a collection. If omitted, fetches the first match across all collections in DIRECTORY.
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
FORMAT - optional. If omitted, output is in human-readable form. Allowed values: abb (AsciiBib), xml (XML).
FILE - optional. Save the document with the given filename. The file extension (abb, xml) defines the output format.
$ relaton collection find TEXT -c COLLECTION -d DIRECTORY
Full-text search through a collection or all collections.
COLLECTION - optional name of a collection. If omitted, searches across all collections.
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
$ relaton collection fetch CODE -t TYPE -y YEAR -c COLLECTION -d DIRECTORY --publication-date-before DATE --publication-date-after DATE
Fetch the Relaton entry for document identifier CODE and save it into COLLECTION.
TYPE - specifies the standards class library. See recognized TYPE values.
YEAR - optional year of publication.
COLLECTION - name of a collection (required).
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
--publication-date-before DATE fetch only documents published before the specified date. Accepted formats: YYYY, YYYY-MM, YYYY-MM-DD.
--publication-date-after DATE fetch only documents published after the specified date. Accepted formats: YYYY, YYYY-MM, YYYY-MM-DD.
$ relaton collection export COLLECTION -d DIRECTORY
Export COLLECTION into an XML file.
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
$ relaton collection import FILE -c COLLECTION -d DIRECTORY
Import a document or collection from XML FILE into COLLECTION.
COLLECTION - optional. If the collection does not exist, it will be created.
DIRECTORY - optional path to a directory with collections. Default: $HOME/.relaton/collections.
$ relaton db create DIR
Create a new cache database in directory DIR (optional, default: $HOME/.relaton/cache). If the target directory exists, it will be used as a database.
$ relaton db fetch CODE -t TYPE -f FORMAT -y YEAR --publication-date-before DATE --publication-date-after DATE
Fetch an entry from the cache database. Arguments are the same as for relaton fetch.
$ relaton db fetch_all TEXT -e EDITION -y YEAR -f FORMAT
Fetch all entries from the cache database.
TEXT - optional, search for a specific string.
EDITION - optional, filter documents by edition.
YEAR - optional, filter documents by year.
FORMAT - optional output format: xml (default), yaml, bibtex.
Open an issue or pull request at https://github.com/relaton/relaton-cli.
This gem is developed, maintained, and funded by Ribose Inc.
BSD 2-Clause. See LICENSE for details.