Functionality

This gem processes Asciidoctor documents following a template for generating UNECE International Standards.

The gem currently inherits from the Metanorma-Standoc gem, and aligns closely to it. Refer to the ISO gem documentation for guidance, including the Authoring Guide.

The following outputs are generated.

• an XML representation of the document, intended as a document model for UNECE International Standards.

• The XML representation is processed in turn to generate the following outputs as end deliverable UNECE standard drafts.

  • HTML

  • Word

Note	AsciiMathML is to be used for mathematical formatting. The gem uses the Ruby AsciiMath parser, which is syntactically stricter than the common MathJax processor; if you do not get expected results, try bracketing terms your in AsciiMathML expressions.

Usage

The preferred way to invoke this gem is via the metanorma script:

$ metanorma --type unece a.adoc                   # output HTML and PDF
$ metanorma --type unece --extensions html a.adoc # output just HTML
$ metanorma --type unece --extensions pdf a.adoc  # output just PDF
$ metanorma --type unece --extensions xml a.adoc  # output UNECE XML

The gem translates the document into UNECE XML format, and then validates its output against the UNECE XML document model; errors are reported to console against the XML, and are intended for users to check that they have provided all necessary components of the document.

The gem then converts the XML into HTML and PDF.

Installation

Quick start

https://www.metanorma.com/overview/getting-started/

macOS

If you are using macOS, the https://github.com/metanorma/metanorma-macos-setup repository has instructions on setting up your machine to run Metanorma scripts such as this one. You need only run the following in a Terminal console:

$ bash <(curl -s https://raw.githubusercontent.com/metanorma/metanorma-macos-setup/master/metanorma-setup)
$ gem install metanorma-unece
$ gem install metanorma-cli

Testing

Since this software is still in development it is not yet as mature as the other standards we support. We plan to fully complete support if there is interest.

The easiest way to try out is using a Mac. It takes a little bit more work on a Windows machine through the platform-independent Docker container (see the Metanorma Quickstart guide) , but it is doable.

The current examples of UNECE documents encoded using Metanorma is provided in https://github.com/metanorma/unece-docs/

(Please run the 2-line macOS setup script prior to the following)

First, use Git to clone the code and documents:

git clone https://github.com/metanorma/unece-docs/

Then, install all dependencies with this command:

bundle

Next, run the compilation toolchain:

make all

Then you will see the files generated, including HTML and Word Doc.

The easiest way to start a new document is to copy one of the two samples and modify them.

Documentation

See The UNECE flavor of Metanorma

Data Models

The UNECE Standard Document format is an instance of the StandardDocument model. Details of this general model can be found on its page.

Details of the UNECE modifications to this general model can be found in the UNECE model repository.

Examples

• Example documents are avalable at the mn-samples-unece repository.