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

metanorma-cli 1.5.16 → 1.5.17.pre

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