metanorma-cli 1.4.16pre → 1.4.18pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67054a6dd8165dd51dd5c6e09f92f5c188746f70957d3f3dcf0e50af8381fadd
-  data.tar.gz: bc8b3a2de726fcc0e1ca392d76b32c7b6bd109dc403477433e5a85a403a332c9
+  metadata.gz: 8eb864d5612a326a357c52312047e5d12023b80e3005d766d54778aa5f5cd5aa
+  data.tar.gz: c3c856e48c5277c6d7e624cc48c0a2907a2093b836424a1d2eebff97e7daab0e
 SHA512:
-  metadata.gz: '0954da279edc2ab06e7c5d42f490cb365fb006bfcb0e6347b98e4994a32778617127fe77501e0c8cdd21f81e69aa045eb62c4c4345e2d1ba1bd8271922639471'
-  data.tar.gz: 46f3382fd089fd01e1bdcf6cfd1c4f7ef863778c49d087aa37bc0ac495dd540fd32babe30246b3727ad32eed3b3ac535da93d6ca40c921686e7a6c9637887681
+  metadata.gz: 37b4a2ecb0b582d28d0330dc0c3011fda684806aaa8b2bb7685a00540c40dba7f76708aea75d1706bdf58738e46f8cf1a73138fcaad38e83966f73dc70e4b2ad
+  data.tar.gz: 7c37e6be7c420fe45f70fdcd3028d2595cc11145dea5a82c1035fdb09a4c07789c42add84db5821436a3dfffdecd4aa59d94587a234cf7c756af717fd6079c34

data/README.adoc

@@ -69,6 +69,41 @@ option.
 metanorma setup --agree-to-terms
 ----
 
+=== External dependencies
+
+The Metanorma toolchain supports certain features when optional dependencies
+are installed. Please refer to the following table for them.
+
+[cols="1,1,1"]
+|===
+|Dependency |Mandatory? | Target component / purpose
+
+|https://git-scm.com/[`git`]
+| :white_check_mark:
+|`metarnoma-cli` (templates), https://github.com/fontist/fontist[`fontist`]
+
+|https://www.oracle.com/java/technologies/[`java`]
+| :white_check_mark:
+|https://github.com/metanorma/mn2pdf[`mn2pdf`], https://github.com/metanorma/metanorma-standoc[`metanorma-standoc`]
+
+|https://xml2rfc.tools.ietf.org/[`xml2rfc`] (`python`)
+| :white_large_square:
+|https://github.com/metanorma/metanorma-ietf[`metanorma-ietf`]
+
+|https://inkscape.org/[`inkscape`]
+| :white_large_square:
+|https://github.com/metanorma/isodoc[`isodoc`], SVG to EMF functionality (for inserting SVGs into Word)
+
+|https://graphviz.org/[`graphviz`]
+| :white_check_mark:
+|https://github.com/lutaml/lutaml[`lutaml`] generation of LutaML diagrams
+
+|http://www.plantuml.com/[`plantuml`]
+| :white_large_square:
+|https://github.com/metanorma/metanorma-standoc[`metanorma-standoc`] generation of PlantUML diagrams
+
+|===
+
 
 === Generate a new Metanorma document using a template  (`metanorma new`)
 

data/docs/installation.adoc

@@ -1,21 +1,89 @@
 = Installation
 
-You can get the `metanorma` command-line executable by installing this Ruby gem.
+The `metanorma` command-line executable is installed by this Ruby gem.
 
 [IMPORTANT]
 ====
-To install the Metanorma toolchain we recommend to use one of the ways described in
-https://www.metanorma.com/author/topics/install/[Metanorma installation] topic.
-Installing this gem by hand may not be the easiest way.
+Users of the Metanorma suite should install Metanorma according to the steps at
+the
+https://www.metanorma.org/author/topics/install/[Metanorma installation guide].
 
-When following this installation method, to start building documents you may have to take care
-of manually installing some required third-party software as well.
-Which exactly depends on what documents you’re building, below notes cover some of that.
+The instructions provided here are intended for Metanorma developers, since
+a number of third-party dependencies will also need to be installed manually.
 ====
 
 
+== Install Ruby
+
+== macOS
+
+While macOS provides a default installation of Ruby, it is restricted in a
+number of ways.
+
+We strongly recommend installing a Ruby outside of the system Ruby using
+`rbenv`.
+
+[source,console]
+----
+# Install Xcode and associated development tools
+$ xcode-select --install
+
+# Install GCC and development tools
+$ brew install autoconf gcc make
+
+# Install rbenv to manage Ruby versions
+# Remember to follow the setup steps by running `rbenv init`!
+$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
+
+# Install Ruby 2.7.4 through rbenv
+$ rbenv install 2.7.4
+
+# Set Ruby 2.7.4 as your global version
+$ rbenv global 2.7.4
+
+# Then restart Terminal.app
+----
+
+
+== Linux
+
+Ruby may not be pre-installed on your Linux distribution.
+
+Please follow the official
+https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide].
+
+== Windows
+
+Ruby is not pre-installed on Windows.
+
+The easiest way to install Ruby is with `RubyInstaller`, as recommended by
+the official
+https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide])
+
+If you prefer an automated way to install, we recommend using
+https://chocolatey.org/install[Chocolatey] with commands below:
+
+[source,console]
+----
+choco install -y msys2 ruby
+refreshenv
+ridk install 3
+----
+
+Those commands will work with both PowerShell and CMD.exe.
+
+
+== Other
+
+Further details (or FAQ) on Ruby installation please visit the official
+https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide].
+
+
+
 == Installing the Metanorma CLI gem
 
+Once Ruby is installed, you can install `metanorma-cli` as a gem:
+
 [source,console]
 ----
 gem install metanorma-cli
@@ -29,33 +97,96 @@ Installing the gem will also install all officially supported Metanorma flavors
 
 === Java
 
-You will have to have a Java runtime installed. (Use `brew cask install java` on macOS.)
+You will have to have a Java runtime installed.
 
-=== Puppeteer
+Use the following commands on various platforms:
 
-*If you are going to generate PDFs from HTML* (which applies to CalConnect Standard Documents),
-you will also need to install the https://github.com/GoogleChrome/puppeteer[Puppeteer] Node library.
+macOS:: Run `brew cask install java`
 
-* Ensure you have Node of at least version 7.6.0:
-** https://nodejs.org/en/download/
-** On macOS you should be able to `brew install node`
-* Ensure you have NPM: https://docs.npmjs.com/getting-started/installing-node
-* Install Puppeteer globally in your system: `npm install -g --save --save-exact puppeteer`
+Linux:: Follow https://www.java.com/en/download/help/linux_install.html[official instructions]
+
+Windows:: Run `choco install -y javaruntime`
 
 === PlantUML
 
 *If your documents include link:/author/topics/document-format/diagrams/[PlantUML diagrams]*,
 PlantUML will have to be installed.
 
-* `brew install plantuml` on MacOS.
-* For Linux, link the PlantUML jar file into a command line executable; see
+macOS:: Run `brew install plantuml`.
+
+Linux:: Link the PlantUML jar file into a command line executable; see
 `.travis.yml` for an example.
 
-If PlantUML is not installed locally, the source PlantUML is incorporated into
-the output document as sourcecode.
+Windows:: Run `choco install -y plantuml`.
+
+If PlantUML diagrams used within a document but there PlantUML is not installed,
+the PlantUML diagram source will be incorporated into the output document as
+source code (i.e. `[source]` style).
+
+=== Graphviz
+
+Graphviz is required by LutaML (and PlantUML) to draw diagrams.
+
+macOS:: Run `brew install graphviz`.
+
+Linux:: Install the appropriate
+https://graphviz.org/download/#linux[available packages] (`apt` or `yum`)
+
+Windows:: Run `choco install -y graphviz`
+
+
+=== xml2rfc
+
+Metanorma IETF requires usage of the `xml2rfc` Python package.
+
+To install Python:
+
+macOS:: `brew install python3`
+
+Windows:: `choco install -y python`
+
+Then install `xml2rfc` with:
+
+[source,console]
+----
+pip3 install xml2rfc
+----
+
+
+=== Inkscape
+
+Optional dependency. Inkscape is needed for SVG-to-EMF conversion functionality.
+
+macOS:: Run `brew install inkscape`
+
+Linux:: See Linux instructions https://inkscape.org/release/[here]
+
+Windows:: Run `choco install -y inkscape`
+
+
+=== LaTeXML
+
+Optional dependency. `LaTeXML` is needed for Metanorma for LaTeX functionality.
+
+Most of the packages from various package manager listed on
+https://dlmf.nist.gov/LaTeXML/get.html are outdated.
+
+Since `LaTeXML` is a `perl` module, a reliable way to install it is with the
+https://metacpan.org/dist/App-cpanminus/view/bin/cpanm[`cpanm` package manager]
+
+[source,console]
+----
+curl -L https://cpanmin.us | perl - --sudo App::cpanminus
+cpanm --notest LaTeXML
+# or
+cpanm --notest git://github.com/brucemiller/LaTeXML.git@9a0e7dc5
+----
+
+Alternative, it also can be installed in the following ways (always check the
+version, because the packages may be outdated):
 
+macOS:: Run `brew install latexml`
 
-== Installation notes for Windows
+Linux (with Snap installed):: Run `snap install latexml`
 
-To be able to compile gem with a native extension you must have `RIDK` installed.
-If you are installing metanorma with chocolatey installation script will do this for you
+Windows:: `choco install -y latexml`

data/docs/usage.adoc

@@ -51,24 +51,20 @@ $ metanorma -t mpfd -r metanorma-mpfd mpfd-bpn.adoc
 
 [source,sh]
 ----
-$ metanorma -h
-Usage: metanorma [options] <file>
-  -t, --type TYPE                       Type of standard to generate: rfc2, rfc3, iso, gb, csd, csand, m3d
-  -x, --extensions EXT1,EXT2,... | all  Type of extension to generate per type:
-  {
-    :rfc2=>{:xmlrfc=>"v2.xml"},
-    :rfc3=>{:xmlrfc=>"v3.xml"},
-    :iso=>{:html=>"html", :html_alt=>"alt.html", :doc=>"doc"},
-    :gb=>{:html=>"html", :doc=>"doc"},
-    :csd=>{:html=>"html", :pdf=>"pdf"},
-    :csand=>{:html=>"html"},
-    :m3d=>{:html=>"html", :doc=>"doc"},
-    :rsd=>{:html=>"html"}
-  }
-  In addition, xml (outside of rfc2, rfc3) generates IsoDoc XML. If the argument is "all" or the option is
-  missing, all available extensions are generated.
-  -f, --format FORMAT              Format of source file: asciidoc (current default, only format supported)
-  -r, --require LIBRARY            Require LIBRARY prior to execution
-  -w, --wrapper                    Create wrapper folder for HTML output
-  -h, --help                       Show this message
+$ metanorma help
+Commands:
+  metanorma collection FILENAME -w, --output-folder=OUTPUT_FOLDER  # Render HTML pages from XML/YAML colection
+  metanorma compile FILENAME                                       # Compile to a metanorma document
+  metanorma config                                                 # Manage configuration file
+  metanorma help [COMMAND]                                         # Describe available commands or one specific command
+  metanorma list-doctypes                                          # List supported doctypes
+  metanorma list-extensions                                        # List supported extensions
+  metanorma new NAME -d, --doctype=DOCTYPE -t, --type=TYPE         # Create new Metanorma document
+  metanorma site                                                   # Manage site for metanorma collections
+  metanorma template-repo                                          # Manage metanorma templates repository
+  metanorma version                                                # Version of the code
+
+Options:
+  -s, [--no-progress], [--no-no-progress]  # Don't show progress for long running tasks (like download)
+                                           # Default: true
 ----

data/lib/metanorma/cli/version.rb

@@ -1,5 +1,5 @@
 module Metanorma
   module Cli
-    VERSION = "1.4.16pre".freeze
+    VERSION = "1.4.18pre".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-cli
 version: !ruby/object:Gem::Version
-  version: 1.4.16pre
+  version: 1.4.18pre
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-13 00:00:00.000000000 Z
+date: 2021-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug