= Metanorma processor for UNECE documents image:https://img.shields.io/gem/v/metanorma-unece.svg["Gem Version", link="https://rubygems.org/gems/metanorma-unece"] image:https://img.shields.io/travis/riboseinc/metanorma-unece/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-unece"] image:https://codeclimate.com/github/riboseinc/metanorma-unece/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-unece"] WARNING: This gem is still under development. == Functionality This gem processes http://asciidoctor.org/[Asciidoctor] documents following a template for generating UNECE International Standards. The gem currently inherits from the https://github.com/riboseinc/metanorma-standoc[Metanorma-Standoc] gem, and aligns closely to it. Refer to the ISO gem documentation for guidance, including https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[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: http://asciimath.org[AsciiMathML] is to be used for mathematical formatting. The gem uses the https://github.com/asciidoctor/asciimath[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: [source,console] ---- $ 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. //// The gem can also be invoked directly within asciidoctor, though this is deprecated: [source,console] ---- $ asciidoctor -b unece -r 'metanorma-unece' a.adoc ---- //// == Installation === Quick start https://www.metanorma.com/overview/getting-started/ === macOS If you are using macOS, the https://github.com/riboseinc/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: [source,console] ---- $ bash <(curl -s https://raw.githubusercontent.com/riboseinc/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 https://www.metanorma.com/overview/getting-started/#docker-setup[Metanorma Quickstart guide]) , but it is doable. The current examples of UNECE documents encoded using Metanorma is provided in https://github.com/riboseinc/unece-docs/ (Please run the 2-line macOS setup script prior to the following) First, use Git to clone the code and documents: [source,console] -- git clone https://github.com/riboseinc/unece-docs/ -- Then, install all dependencies with this command: [source,console] -- bundle -- Next, run the compilation toolchain: [source,console] -- 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. == Approach === Document model The UNECE Standard Document model is an instance of the https://github.com/riboseinc/metanorma-model-standoc[StandardDocument model]. The UNECE format ("UNECE XML") intends to introduce rigor into the UNECE standards authoring process, and is prescribed in a separate document. === Asciidoctor Asciidoctor has been selected as the authoring tool to generate the document model representation of UNECE standards. It is a document formatting tool like Markdown and DocBook, which combines the relative ease of use of the former (using relatively lightweight markup), and the rigor and expressively of the latter (it has a well-defined syntax, and was in fact initially developed as a DocBook document authoring tool). Asciidoctor has built-in capability to output Text, DocBook and HTML; so it can be used to preview the file as it is being authored. Generating documents via a document model substantially automated formatting associated with the document, including automating numbering of headings, figures, tables etc, and automatically generating references and citations. == Document Attributes === Common attributes The gem relies on Asciidoctor document attributes to provide necessary metadata about the document. These include: `:edition:`:: The document edition `:revdate:`:: The date the document was last updated `:copyright-year:`:: The year which will be claimed as when the copyright for the document was issued `:title:`:: The main component of the English title of the document (mandatory). (The first line of the AsciiDoc document, which contains the title introduced with `=`, is ignored) `:doctype:`:: The document type (see _UNECE deliverables: The different types of UNECE publications_) (mandatory). Note that the document types are reflected in the document identifier. The permitted types for UNECE are: + -- recommendation:: UNECE Recommendation plenary:: UNECE Plenary document -- `:status:``:: The document status. The permitted types are: `proposal`, `working-draft`, `committee-draft`, `draft-standard`, `final-draft`, `published`, `withdrawn`. `:committee:`:: The name of the relevant UNECE committee, for example, `United Nations Centre for Trade Facilitation and Electronic Business (UN/CEFACT)` (mandatory) `:language:` :: The language of the document (only `en` for now) (mandatory) `:script:` :: The language of the document (only `Latn` for now) (mandatory) `:toc:` :: Include table of contents in Word output. (Table of contents is always included in HTML output.) NOTE: The attribute `:draft:`, if present, includes review notes in the XML output; these are otherwise suppressed. === Recommendation specific attributes `:docnumber:`:: The document number if the document is a Recommendation. e.g. `42` for Recommendation 42, which happens to be the ultimate answer. (mandatory for Recommendation) === Plenary document specific attributes `:session-date:`:: Date of the session where this document will be discussed. e.g. `Geneva, 30 April – 1 May 2018` `:agenda-item:`:: Number of the agenda item this document belongs to. e.g. `Item 6 of the provisional agenda` `:collaborator:`:: Collaborator of this document, if any. e.g. `World Economic Forum` `:agenda-id:`:: The unique ID number of this agenda item. e.g. `ECE/TRADE/C/CEFACT/2018/6` `:distribution:`:: Extent of distribution allowed. e.g. `General` [[model_additions]] == Asciidoctor model additions Refer also to https://github.com/riboseinc/metanorma-standoc/blob/master/README.adoc; this section lists additions specific only to metanorma-unece === Abstract A clause is recognised as an abstract if it is prefixed with the `[abstract]` style attribute: [source,asciidoctor] -- [abstract] == Summary In 2017, the World Economic Forum approached UN/CEFACT in order to create a guide on Paperless Trade which might help countries to understand and implement specific provisions of the World Trade Organization?~@~Ys Trade Facilitation Agreement, specifically article 10 on Formalities connected with importation and exportation (10.2, 10.3 and 10.4) as well as article 7 on Release and clearance of goods (7.1 and 7.2). -- Abstracts are moved to the front page in plenary documents. In recommendation documents, they appear in the document preface, before the foreword and introduction. === Paragraph numbering Paragraphs are automatically numbered in this gem, and paragraph numbers should not be entered in the Asciidoctor source. Paragraphs are numbered by treating each paragraph in the Metanorma XML as a separate clause; all terminal clauses in UNECE Metanorma XML are rendered as a numbered paragraph. Non-paragraph blocks (tables, figures, admonitions, lists) are not numbered; nor are paragraphs in prefatory material (introduction, foreword, abstract). === Admonitions The admonition container "IMPORTANT" is used to render UNECE document boxes. Unlike normal Metanorma admonitions, UNECE admonitions can have titles: [source,asciidoctor] -- [IMPORTANT] .Business Process Analysis Plus (BPA+) (<==== This is the box title) ==== Business Process Analysis was initially designed to document and evaluate an import/export process at a given point time and its relative simplicity. It also specifically includes a measurement of the time and cost of the complete range of procedures as one of the main outputs of the analysis. This combination makes it suitable as the basis/core of a trade facilitation monitoring and improvement system. ==== -- == Data Models The UNECE Standard Document format is an instance of the https://github.com/riboseinc/metanorma-model-standoc[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 https://github.com/riboseinc/metanorma-model-unece[UNECE model] repository. == Examples * link:spec/examples/plenary.adoc[] is the source file for the "`ECE/TRADE/C/CEFACT/2018/6`" plenary document. * link:spec/examples/rec42.adoc[] is the source file for Recommendation 42. * link:spec/examples/rfc6350.adoc[] is the UNECE version of https://tools.ietf.org/html/rfc6350[RFC 6350].