metanorma-cli 1.1.8 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17e6241712028d756a1aa8fbfdb9071f430850fc70095eb7899c5040a32286fa
-  data.tar.gz: c338a1af3c9eaf0adaafb61581df07d8e579cdb690face35fd0d5717e27ea81e
+  metadata.gz: 257a0c33f07f9b412bf11de5c0dfeea4025dc05ec54ec3c69aea9b1eb205df35
+  data.tar.gz: bb4c121dd0d9d142097138da52a054f1a65321d7953bc0eeba0e71c8f122ba2c
 SHA512:
-  metadata.gz: a84bb780427cd9cc7f4ac9c45dee1b2dd4a9a7ac30ee8d2eda5ba896c847c26595e3f323b124b867c2f50b36c7f26ee3be4fe590897d669c8cc6d13a6d64b83b
-  data.tar.gz: b5dc3027dfa5525d840745c30a5fa4f12f83bf9cb3d03eae2260568603e7c65d795fa7226cc018c9255e82c6b27bc9067728a80cde5db101d21bb122e0c3f188
+  metadata.gz: 74866f346a2651bb295d881b42a846f66508cd6db1c2b33b5c2705ee4be11f963f06f611ed3b2c17ddd6428091b25d0fdf2baf264d66cc7428bcaf9946cb4276
+  data.tar.gz: 2152501a0b8e242f98f29ce0d08f961146efc95945b51fee4523684fc3bacc915fceef21426ba764466aece1e58f5ab05906ef9d69de2c43aeb000f452e7756f

data/Gemfile.lock

@@ -1,23 +1,21 @@
 PATH
   remote: .
   specs:
-    metanorma-cli (1.1.8)
+    metanorma-cli (1.2.0)
       git (~> 1.5)
-      isodoc (~> 0.9.0)
+      isodoc (~> 0.10.0)
       metanorma (~> 0.3.9)
-      metanorma-acme (~> 1.1.0)
-      metanorma-csand (~> 1.1.0)
-      metanorma-csd (~> 1.1.0)
-      metanorma-gb (~> 1.1.0)
+      metanorma-acme (~> 1.2.0)
+      metanorma-csand (~> 1.2.0)
+      metanorma-csd (~> 1.2.0)
+      metanorma-gb (~> 1.2.0)
       metanorma-ietf (~> 1.0.1)
-      metanorma-iso (~> 1.1.0)
-      metanorma-m3d (~> 1.1.0)
-      metanorma-mpfd (~> 0.1.0)
-      metanorma-nist (~> 0.0.1)
-      metanorma-ogc (~> 0.0.1)
-      metanorma-rsd (~> 1.1.0)
-      metanorma-standoc (~> 1.1.0)
-      metanorma-unece (~> 0.0.1)
+      metanorma-iso (~> 1.2.0)
+      metanorma-m3d (~> 1.2.0)
+      metanorma-nist (~> 0.1.0)
+      metanorma-ogc (~> 0.1.0)
+      metanorma-standoc (~> 1.2.0)
+      metanorma-unece (~> 0.1.0)
       nokogiri (>= 1)
       thor (~> 0.20.3)
 
@@ -39,14 +37,10 @@ GEM
     diff-lcs (1.3)
     equivalent-xml (0.6.0)
       nokogiri (>= 1.4.3)
-    ffi (1.9.25)
+    ffi (1.11.1)
     gb-agencies (0.0.5)
-    gbbib (0.4.4)
-      cnccs (~> 0.1.1)
-      gb-agencies (~> 0.0.1)
-      iso-bib-item (~> 0.4.2)
     git (1.5.0)
-    html2doc (0.8.10)
+    html2doc (0.8.11)
       asciimath (~> 1.0.7)
       htmlentities (~> 4.3.4)
       image_size
@@ -56,132 +50,108 @@ GEM
       uuidtools
     htmlentities (4.3.4)
     httpclient (2.8.3)
-    iecbib (0.2.2)
-      addressable
-      iso-bib-item (~> 0.4.2)
-    ietfbib (0.4.6)
-      iso-bib-item (~> 0.4.2)
     iev (0.2.2)
       nokogiri
-    image_size (2.0.0)
+    image_size (2.0.1)
     iso-639 (0.2.8)
-    iso-bib-item (0.4.5)
-      isoics (~> 0.1.6)
-      nokogiri (~> 1.8.4)
-      ruby_deep_clone (~> 0.8.0)
-    isobib (0.4.4)
-      algoliasearch
-      iecbib (~> 0.2.1)
-      iso-bib-item (~> 0.4.2)
-    isodoc (0.9.23)
+    isodoc (0.10.0)
       asciimath
-      html2doc (~> 0.8.6)
+      html2doc (~> 0.8.11)
       htmlentities (~> 4.3.4)
       liquid
       metanorma (~> 0.3.0)
       nokogiri (>= 1)
       rake (~> 12.0)
       roman-numerals
-      sassc (~> 1.12.1)
+      sassc (~> 2)
       thread_safe
       uuidtools
     isoics (0.1.7)
     json (2.2.0)
     liquid (4.0.3)
-    metanorma (0.3.11)
+    metanorma (0.3.12)
       asciidoctor
       htmlentities
-    metanorma-acme (1.1.4)
+    metanorma-acme (1.2.0)
       asciidoctor (~> 1.5.7)
       htmlentities (~> 4.3.4)
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
       ruby-jing
-    metanorma-csand (1.1.5)
+    metanorma-csand (1.2.0)
       asciidoctor (~> 1.5.7)
       asciimath
       htmlentities (~> 4.3.4)
       image_size
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
       mime-types
       nokogiri
       ruby-jing
       thread_safe
       uuidtools
-    metanorma-csd (1.1.4)
-      isodoc (~> 0.9.6)
-      metanorma-standoc (~> 1.1.0)
-    metanorma-gb (1.1.5)
+    metanorma-csd (1.2.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
+    metanorma-gb (1.2.0)
       gb-agencies (~> 0.0.4)
       htmlentities (~> 4.3.4)
-      isodoc (~> 0.9.1)
-      metanorma-iso (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-iso (~> 1.2.0)
       twitter_cldr (~> 4.4.4)
-    metanorma-ietf (1.0.1)
-      isodoc (~> 0.9.6)
-      metanorma-standoc (~> 1.1.0)
-    metanorma-iso (1.1.6)
+    metanorma-ietf (1.0.3)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
+    metanorma-iso (1.2.0)
       asciidoctor (~> 1.5.7)
-      iev (~> 0.2.0)
-      isodoc (~> 0.9.8)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
       ruby-jing
-    metanorma-m3d (1.1.5)
+    metanorma-m3d (1.2.0)
       asciidoctor (~> 1.5.7)
       asciimath
       htmlentities (~> 4.3.4)
       image_size
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
       mime-types
       nokogiri
       ruby-jing
       thread_safe
       uuidtools
-    metanorma-mpfd (0.1.10)
-      asciidoctor (~> 1.5.7)
-      htmlentities (~> 4.3.4)
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
-      nokogiri
-      twitter_cldr
-    metanorma-nist (0.0.8)
+    metanorma-nist (0.1.0)
       asciidoctor (~> 1.5.7)
       htmlentities (~> 4.3.4)
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
+      relaton-nist (~> 0.2.0)
       ruby-jing
       twitter_cldr
-    metanorma-ogc (0.0.9)
+      tzinfo-data
+    metanorma-ogc (0.1.0)
       asciidoctor (~> 1.5.7)
       htmlentities (~> 4.3.4)
       iso-639
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
       ruby-jing
-    metanorma-rsd (1.1.4)
-      asciidoctor (~> 1.5.7)
-      htmlentities (~> 4.3.4)
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
-      nokogiri
-    metanorma-standoc (1.1.9)
+    metanorma-standoc (1.2.0)
       asciidoctor (~> 1.5.7)
       concurrent-ruby
-      html2doc (~> 0.8.0)
+      html2doc (~> 0.8.11)
       iev (~> 0.2.1)
-      isodoc (~> 0.9.0)
-      relaton (~> 0.3.1)
+      isodoc (~> 0.10.0)
+      relaton (~> 0.4.0)
+      relaton-cli (~> 0.2.0)
       ruby-jing
       sterile (~> 1.0.14)
       unicode2latex (~> 0.0.1)
-    metanorma-unece (0.0.14)
+    metanorma-unece (0.1.0)
       asciidoctor (~> 1.5.7)
       htmlentities (~> 4.3.4)
       iso-639
-      isodoc (~> 0.9.0)
-      metanorma-standoc (~> 1.1.0)
+      isodoc (~> 0.10.0)
+      metanorma-standoc (~> 1.2.0)
       roman-numerals
       ruby-jing
       twitter_cldr
@@ -190,26 +160,49 @@ GEM
     mime-types-data (3.2019.0331)
     mini_portile2 (2.3.0)
     mixlib-shellout (2.4.4)
-    nistbib (0.1.5)
-      relaton-bib (~> 0.1.0)
     nokogiri (1.8.5)
       mini_portile2 (~> 2.3.0)
     optout (0.0.2)
-    public_suffix (3.0.3)
+    public_suffix (3.1.0)
     rake (12.3.2)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.10.0)
-      ffi (~> 1.0)
-    relaton (0.3.4)
+    relaton (0.4.0)
       algoliasearch
-      gbbib (~> 0.4.0)
-      iecbib (~> 0.2.0)
-      ietfbib (~> 0.4.2)
-      iso-bib-item (~> 0.4.2)
-      isobib (~> 0.4.0)
-      nistbib (~> 0.1.1)
-    relaton-bib (0.1.1)
+      relaton-gb (~> 0.5.0)
+      relaton-iec (~> 0.3.0)
+      relaton-ietf (~> 0.5.0)
+      relaton-iso (~> 0.5.0)
+      relaton-iso-bib (~> 0.2.0)
+      relaton-itu (~> 0.2.0)
+      relaton-nist (~> 0.2.0)
+    relaton-bib (0.2.1)
+      addressable
       nokogiri (~> 1.8.4)
+    relaton-cli (0.2.0)
+      liquid
+      relaton (~> 0.4)
+      thor
+    relaton-gb (0.5.0)
+      cnccs (~> 0.1.1)
+      gb-agencies (~> 0.0.1)
+      relaton-iso-bib (~> 0.2.0)
+    relaton-iec (0.3.0)
+      addressable
+      relaton-iso-bib (~> 0.2.0)
+    relaton-ietf (0.5.0)
+      relaton-iso-bib (~> 0.2.0)
+    relaton-iso (0.5.0)
+      algoliasearch
+      relaton-iec (~> 0.3.0)
+      relaton-iso-bib (~> 0.2.0)
+    relaton-iso-bib (0.2.2)
+      isoics (~> 0.1.6)
+      nokogiri (~> 1.8.4)
+      relaton-bib (~> 0.2.0)
+      ruby_deep_clone (~> 0.8.0)
+    relaton-itu (0.2.0)
+      relaton-iso-bib (~> 0.2.0)
+    relaton-nist (0.2.0)
+      relaton-bib (~> 0.2.0)
     roman-numerals (0.3.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -219,29 +212,24 @@ GEM
       mixlib-shellout (~> 2.0)
       rspec (~> 3.2)
       rspec-its (~> 1.2)
-    rspec-core (3.8.0)
+    rspec-core (3.8.1)
       rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.3)
+    rspec-expectations (3.8.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
-    rspec-mocks (3.8.0)
+    rspec-mocks (3.8.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
+    rspec-support (3.8.2)
     ruby-jing (0.0.1)
       optout (>= 0.0.2)
     ruby_deep_clone (0.8.0)
-    sass (3.7.4)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-    sassc (1.12.1)
-      ffi (~> 1.9.6)
-      sass (>= 3.3.0)
+    sassc (2.0.1)
+      ffi (~> 1.9)
+      rake
     sterile (1.0.14)
       nokogiri
     thor (0.20.3)
@@ -252,6 +240,8 @@ GEM
       tzinfo
     tzinfo (2.0.0)
       concurrent-ruby (~> 1.0)
+    tzinfo-data (1.2019.1)
+      tzinfo (>= 1.0.0)
     unicode2latex (0.0.2)
     uuidtools (2.1.5)
 

data/README.adoc

@@ -1,4 +1,4 @@
-= Metanorma's command-line interface (CLI)
+= Metanorma command-line interface (CLI)
 
 image:https://img.shields.io/gem/v/metanorma-cli.svg["Gem Version", link="https://rubygems.org/gems/metanorma-cli"]
 image:https://img.shields.io/travis/metanorma/metanorma-cli/master.svg["Build Status", link="https://travis-ci.org/metanorma/metanorma-cli"]
@@ -14,11 +14,192 @@ Depending on your setup, you may find quicker ways to get started:
 please refer to https://www.metanorma.com/docs/getting-started/[Getting Started] instead.
 ====
 
-At its core, installing this gem is as easy as `gem install metanorma-cli`.
-That will install the `metanorma` executable, which you can use with all
+To install this gem, simply run:
+
+[source,sh]
+----
+gem install metanorma-cli
+----
+
+This will install the `metanorma` executable, which you can use with all
 officially supported Metanorma flavors (such as ISO, CalConnect, IETF, etc).
-However, certain dependencies such as Puppeteer may have to be installed separately,
-and the process is a little more complex if you’re using Windows.
 
-For advanced details regarding dependencies and Windows installation notes,
-refer to the link:docs/installation.adoc[full installation manual].
+However, a number of dependencies (such as Puppeteer and LaTeXML) are not
+installed with this gem, and have to be installed separately.
+The process of installing the full suite can be a little more complex.
+
+Generally, we recommend you to follow steps given at
+https://www.metanorma.com/author/topics/install/[Metanorma Installation].
+
+But if you aren't afraid of tinkering deeply, please see the
+link:docs/installation.adoc[Developer Installation Notes]
+for advanced details regarding dependencies and Windows installation notes.
+
+
+== Usage
+
+=== Generate a new Metanorma document using a template  (`metanorma new`)
+
+Metanorma CLI allows you to create a new document using an official
+template, or a user-specified custom template.
+
+To see what options are available under the `new` command,
+run `metanorma help new`.
+
+==== Generate a new document from an official Metanorma template (from an official Metanorma template repository)
+
+The `metanorma new` command allows you to create a document by running a
+single command.
+
+To create a new document using an official template you simply
+invoke the command with the mandatory options `type` and `doctype`,
+then Metanorma will find and load the official template to
+create your document.
+
+For example, if you want to create a new CSD document (`type`: `csd`) called
+`csd-foo-standard`, using the `standard` template type,
+run the following command:
+
+[source, sh]
+----
+metanorma new -d standard -t csd csd-foo-standard
+----
+
+This will create your barebones document and will also print out
+all files created during generation.
+
+Currently, the supported Metanorma template types are `csd`, `ogc` and `iso`.
+
+
+==== Generate a new document from a custom Metanorma template repository
+
+The CLI allows using custom or unofficial template repositories, meaning you
+could also generate a new document using your own custom template.
+
+Metanorma supports two types of template repositories:
+
+* Git: a Git repository (local or remote, public or private)
+* Local: a directory
+
+Once a template repository and a template within is specified, Metanorma will
+automatically download and generate the new document using your custom template.
+
+For example, if you want to create a new CSD document with the
+following parameters:
+
+* Document name: `my-custom-csd-document`
+* Flavor: `csd`
+* Doctype: `standard`
+* Template: `https://gitfoo.com/foobar/mn-templates-foobar` (fictitious example)
+
+You could execute the following command to do so:
+
+[source,sh]
+----
+metanorma new -d standard -t csd \
+  -l https://gitfoo.com/foobar/mn-templates-foobar my-custom-csd-document
+----
+
+Here's an example of using a local directory:
+
+[source,sh]
+----
+metanorma new -d standard -t csd \
+  -l ~/shared/mn-templates my-custom-csd-document
+----
+
+
+=== Compile a document (`metanorma compile` or just `metanorma`)
+
+The key functionality of this CLI is to allow compilation of a Metanorma document.
+The command `metanorma help compile` will display all usage instructions of
+the `compile` command shown with available options.
+
+[source]
+----
+Usage:
+  metanorma compile FILENAME [..options]
+
+Options:
+  -t, [--type=TYPE]                   # Type of standard to generate
+  -x, [--extensions=EXTENSIONS]       # Type of extension to generate per type
+  -f, [--format=FORMAT]               # Format of source file: eg. asciidoc
+                                      # Default: asciidoc
+
+  -r, [--require=one two three]       # Require LIBRARY prior to execution
+  -w, [--wrapper], [--no-wrapper]     # Create wrapper folder for HTML output
+  -a, [--asciimath], [--no-asciimath] # Keep Asciimath in XML output instead of converting it to MathM
+  -R, [--relaton=RELATON]             # Export Relaton XML for document to nominated filename
+  -e, [--extract=EXTRACT]             # Export sourcecode fragments from this document to nominated directory
+  -v, [--version=VERSION]             # Print version of code (accompanied with -t)
+----
+
+So, let's put this in use. For example we have a document `my-iso-document.adoc`
+and we want to compile this using `iso` and `html` as extension, then we can use
+the following command.
+
+[source, sh]
+----
+metanorma compile --type iso -x html my-iso-document.adoc
+# or just
+metanorma --type iso -x html my-iso-document.adoc
+----
+
+This should compile any valid document, but if there are some issues then it
+will also print those out in the terminal. Currently, the supported flavors
+are `ietf`, `iso`, `gb`, `csd`, `csand`, `m3d` and `rsd`.
+
+
+=== List supported output formats (`metanorma list-extensions`)
+
+Need to know what output formats are supported for a given flavor?
+We've got you covered.
+
+To list out the output formats supported by every single flavor type,
+run the following command:
+
+[source,sh]
+
+----
+metanorma list-extensions
+----
+
+
+To list out the output formats supported by a particular flavor type,
+run the following command:
+
+[source,sh]
+----
+metanorma list-extensions <flavor>
+----
+
+e.g.,
+
+[source,sh]
+----
+metanorma list-extensions iso
+----
+
+
+=== Show processor version (`metanorma version`)
+
+The `version` command returns the version of the Metanorma processor for
+a specific flavor.
+
+e.g., to know the currently running version for `iso`, then we
+can use the following command and this will show the current version that we are
+using for that specific processor.
+
+[source, sh]
+----
+metanorma version --type iso
+----
+
+
+== Credits
+
+This gem is developed, maintained and funded by https://www.metanorma.com/docs/getting-started/[Ribose Inc.]
+
+== License
+
+The gem is available under the terms of the http://opensource.org/licenses/MIT[MIT License].