RubyGems - metanorma-cli - Versions diffs - 1.5.16 → 1.5.17.pre - Mend

metanorma-cli 1.5.16 → 1.5.17.pre

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 609828cadbd84334657265179daa52a62070d0cb174c8ea2428e47260b4791c8
-  data.tar.gz: 6e786ca834be4d03c2f82d5e898c44d1b0d7503e0b06668364ba0f27f7919171
+  metadata.gz: 06706da792dc196206c59fad06a218c91a3a9729b3aeac213512b6f90fe95bae
+  data.tar.gz: 84ea680e6c15aaedc94b35eb1630432cdd860527080bcfbf46219e80f34838ee
 SHA512:
-  metadata.gz: f99251b43e2f21febf44b4acda4f6b44dc22a569e9b1e3c72ebc6cceaaf51a27e61f2323714a877154efbd76b516f42fac14bc3e7b662eeba4c8b7cd95d88456
-  data.tar.gz: 07dd0d8d1a3276a327ac83ad99dcc2bb998abbe84b7637636a82cdafea3ff6514a59ec90d986b0223de5c8287ab75323f5da6d22394923ba7254f9c43ba25f2d
+  metadata.gz: b88a55b4f74db10fe759cb023e726289176f9844becf78a75cdeeedbf0c9adc8a3bcc8dbab596477c009a797de2330a393728f1c0f6cdba6a2fc61e45080e445
+  data.tar.gz: 9997f212e82b1299731f75915342b9dea6127f858d3de4da2d4f6425ead2bad7bc8a4ba01bcee89f27df59803368f97866afae534fd0c52ce06f6e941c62eda5

data/README.adoc CHANGED Viewed

@@ -33,42 +33,10 @@ 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]
+https://www.metanorma.com/install/manual-installation/[Developer Installation Notes]
 for advanced details regarding dependencies and Windows installation notes.
-== Usage
-=== Setting up
-Metanorma CLI helps you install necessary fonts used by particular flavors,
-as long as those fonts have a license that allow you to install them.
-For example, ISO relies on Cambria while ITU relies on Arial, which are both not
-supplied by default on Linux. Due to licensing terms, you are allowed to
-install them yourself.
-By running the `metanorma setup` command, Metanorma will identify fonts not
-available on your system, and helps you install them once you agree to
-the license terms presented by those fonts.
-Typically run the command below.
-[source, sh]
-----
-metanorma setup
-----
-If you are sure you want to agree with all the font licensing terms,
-such as during non-interactive runs for continuous integration,
-you can explicitly agree to all terms using the `--agree-to-terms`
-option.
-[source, sh]
-----
-metanorma setup --agree-to-terms
-----
 === External dependencies
 The Metanorma toolchain supports certain features when optional dependencies
@@ -105,273 +73,9 @@ are installed. Please refer to the following table for them.
 |===
-=== 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`.
-=== Compile a document collection (`metanorma collection`)
-This functionality compiles collections of Metanorma documents. It compiles
-the individual documents comprising the collection; then it compiles a document
-acting as a container for those collections. See
-https://github.com/metanorma/metanorma/wiki/Metanorma-collections[],
-https://github.com/metanorma/metanorma-cli/blob/master/spec/fixtures/collection1.yml[]
-The file argument to the collection command is a Metanorma Collections YAML file,
-which contains:
-* Directives on how the collection should be generated
-* Metadata about the collection
-* A manifest listing the documents contained in the collection, in nested hierarchy
-* Content to put at the beginning of the collection container
-* Content to put at the ending of the collection container
-Documents within a collection
-may cross-reference each other using the syntax
-`* [[[myanchor,repo:(current-metanorma-collection/mydoc)]]]`,
-as proposed in https://github.com/metanorma/metanorma/issues/57, where
-`mydoc` is be the value of docref/identifier corresponding to the target document,
-as set in the YAML manifest.
-The output directory will contain:
-* The documents referenced in the manifest, with any citations of other documents in the collection
-resolved, in the output formats requested
-* If `xml` or `presentation` are requested as formats, a concatenated `collection.xml` and/or
-`collection.presentation.xml` file, containing all the documents in the collection.
-* If `html` is requested as a format, an `index.html` HTML page, populated from a provided
-Liquid template coverpage, and linking to all the documents in the manifest.
-[source]
-----
-Usage:
-  metanorma collection FILENAME [..options]
-Options:
-  -x, [--extensions=EXTENSIONS]     # Type of extension to generate
-  -w, [--output-folder=FOLDER]      # Folder to generate collection in
-  -c, [--coverpage=COVERPAGE]       # Cover page as Liquid template for collection (currently HTML only)
-----
-=== List supported doctypes (`metanorma list-doctypes`)
-You want to know what are the supported doctypes and what do they support for
-input and output format? Well, the `metanorma list-doctypes` can help.
-[source,sh]
-----
-metanorma list-doctypes
-----
-To list out the details for a specific flavor run the following command:
-[source,sh]
-----
-metanorma list-doctypes <flavor>
-----
-e.g.,
-[source,sh]
-----
-metanorma list-doctypes iso
-----
-=== 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
-----
-=== Add new template repository (`metanorma template-repo add`)
-The `template-repo add` interface allows you to add your custom template
-repository to metanorma, so next time when you need to generate a new document
-then you can directly use that name to use your custom template from that
-repository.
-[source, sh]
-----
-metanorma template-repo add my-iso https://github.com/you/my-iso-template
-----
-=== Generate metanorma minisite
-The `site` interface allows you to manage mini site generation using the CLI.
-To generate a mini site you need to provide the `SOURCE_PATH` and the CLI will
-take care of compiling each of those files and generate deployable site in the
-provided output directory.
-This interface also supports a YAML manifest file that can be used to customize
-the site generation process. You can check more details here: link:./spec/fixtures/metanorma.yml[metanorma.yml]
-[source, sh]
-----
-metanorma site generate SOURCE_PATH -o OUTPUT_PATH -c metanorma.yml
-----
-=== Using with proxy
-The `metanorma` command can read proxy settings from the following
-environment variables:
-* `HTTP_PROXY` for HTTPS and HTTP proxies
-* `SOCKS_PROXY` for SOCKS proxies
-Please refer to our https://www.metanorma.org/blog/2021-07-20/metanorma-with-proxies/[announcement on proxy support] for details.
+== Usage
-NOTE: Since `metanorma` uses Git for templates (and fonts via Fontist, which also relies on Git),
-Git must also be configured to use proxies. Please refer to
-https://gist.github.com/evantoli/f8c23a37eb3558ab8765[this Gist by evantoli] for details.
+Refer to https://www.metanorma.org/install/usage[Metanorma CLI usage].
 == Credits

data/docs/installation.adoc CHANGED Viewed

@@ -1,187 +1,3 @@
 = Installation
-The `metanorma` command-line executable is installed by this Ruby gem.
-[IMPORTANT]
-====
-Users of the Metanorma suite should install Metanorma according to the steps at the https://www.metanorma.org/author/topics/install/[Metanorma installation guide].
-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 is sometimes included with Linux. To see if you already have it (and check the version):
-1. Open a console/terminal
-2. Type `ruby -v`
-If Ruby is installed, you'll see something like the following
-[source, console]
-----
-ruby 3.1.0p0 (2021-12-25 revision fb4df44d16) [x86_64-linux]
-----
-If not, follow the official
-https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide].
-== Windows
-Ruby is not pre-installed on Windows. There are several ways to install it:
-. For an *easy* experience, use `RubyInstaller`, via the official https://www.ruby-lang.org/en/documentation/installation[Ruby installation guide])
-. For a  more *developer-friendly* experience, install Ruby via a Linux distribution (like Ubuntu) hosted in the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/). [Install WSL2]((https://docs.microsoft.com/en-us/windows/wsl/install), and then [Install Ruby](https://gorails.com/setup/ubuntu/21.04).
-. For a *simpler command-line* experience, first install the [Chocolatey](https://chocolatey.org/install) package manager, then add Ruby packaged with [the MSYS2 build tools](https://www.msys2.org/). This process is explained below:
-.. Open a command prompt (`cmd.exe`) or *PowerShell* console.
-.. Type `choco install -y msys2 ruby`. (If you have a firewall, you may be prompted to allow *dirmngr.exe* and *pacman.exe*. These are part of Ruby and are safe).
-.. When the installation completes, type `refreshenv` to make Ruby available to you.
-.. Type `ridk install 3` to complete the installation of Ruby version 3. This make take a while.
-== Other Ruby Resources
-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
-----
-Installing the gem will also install all officially supported Metanorma flavors
-(such as ISO, CalConnect, IETF, etc).
-== Dependencies
-=== Java
-You will have to have a Java runtime installed.
-Use the following commands on various platforms:
-macOS:: Run `brew cask install java`
-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.
-macOS:: Run `brew install plantuml`.
-Linux:: Link the PlantUML jar file into a command line executable; see
-`.travis.yml` for an example.
-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`
-Linux (with Snap installed):: Run `snap install latexml`
-Windows:: `choco install -y latexml`
+Refer to https://metanorma.org/install/manual-installation/[Metanorma Manual Installation]

data/docs/usage.adoc CHANGED Viewed

@@ -1,105 +1,3 @@
 = Using the Metanorma CLI
-== Usage samples
-For a single document:
-[source,sh]
-----
-$ metanorma iso-my-standard-document.adoc
-----
-or
-[source,sh]
-----
-$ metanorma --type iso -x html iso-my-standard-document.adoc
-----
-if type and extensions are not defined in adoc header
-== Full syntax & options
-General help message can be shown by `metanorma help`
-[source,sh]
-----
-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
-----
-Also you can get a help message for a specific command for example `metanorma help compile`:
-[source,sh]
-----
-Usage:
-  metanorma compile FILENAME
-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=REQUIRE]                                        # 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
-  -d, [--datauriimage], [--no-datauriimage]                      # Encode HTML output images as data URIs
-  -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)
-  -o, [--output-dir=OUTPUT_DIR]                                  # Directory to save compiled files
-      [--agree-to-terms], [--no-agree-to-terms]                  # Agree / Disagree with all third-party licensing terms presented (WARNING: do know what you are agreeing with!)
-      [--no-install-fonts], [--no-no-install-fonts]              # Skip the font installation process
-      [--continue-without-fonts], [--no-continue-without-fonts]  # Continue processing even when fonts are missing
-  -s, [--no-progress], [--no-no-progress]                        # Don't show progress for long running tasks (like download)
-                                                                 # Default: true
-Compile to a metanorma document
-----
-A bit more details on options:
-`type`:: (mandatory, specified via `--type` or `-t`) takes one of the following types:
-`rfc2`, `rfc3`, `iso`, `gb`, `csd`, `csand`, `m3d`, `rsd`. Each of these corresponds to a
-standards class and a Metanorma gem; the list of standards classes supported by the script
-by default will grow (see also `require`).
-`extension`:: (optional) specifies the output formats to be generated. If not specified,
-all possible output formats are generated. The output formats generated are constrained by
-what has been defined for each standard type. All standards can generate Metanorma XML (`xml`),
-and at least one of HTML (`html`), DOC (`doc`), PDF (`pdf`). Some standards generate alternative
-HTML renderings (e.g. `html_alt` for ISO).
-Actual list of supported `types` and `extension`s you can get with `metanorma list-doctypes`
-`wrapper`:: create a separate folder for each instance of HTML output generated; the folder is named
-the same as the output file, without the `.html` suffix. Used to make distribution of HTML outputs
-more straightforward.
-`format`:: (optional, defaults to `asciidoc`, specified via `--format` or `-f`) only accepts `asciidoc` for now
-`require`:: If you wish to use metanorma with a document class which has not been included in the types recognised
-by the metanorma script, you will need to name the corresponding Metnorma gem explicitly with the `-r`
-option. For example:
-[source,sh]
-----
-$ metanorma -t mpfd mpfd-bpn.adoc
-[metanorma] Error: mpfd is not a supported standard type.
-$ metanorma -t mpfd -r metanorma-mpfd mpfd-bpn.adoc
-----
+Refer to https://www.metanorma.org/install/man[Metanorma CLI Manual] and https://www.metanorma.org/install/usage[Metanorma CLI usage]

data/lib/metanorma/cli/version.rb CHANGED Viewed

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

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-cli
 version: !ruby/object:Gem::Version
-  version: 1.5.16
+  version: 1.5.17.pre
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-05-17 00:00:00.000000000 Z
+date: 2022-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: debug
@@ -508,11 +508,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.3.9
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Metanorma is the standard of standards; the metanorma gem allows you to create