Gem Version Build Status Code Climate

Warning
This gem is still under development.

Functionality

This gem processes Metanorma documents into the OGC document class.

It provides the following functions:

  1. Compiles Metanorma input into the Metanorma-OGC XML format

  2. Validates XML output against the Metanorma-OGC 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.

  3. Metanorma-OGC XML is then converted into desired output formats.

The following outputs are supported:

  • Primary: the canonical Metanorma-OGC XML representation (.xml).

  • Secondary: the Metanorma-OGC XML representation is processed to generate the following outputs as end deliverable OGC documents.

    • HTML (.html)

    • PDF (.pdf)

    • Word (.doc)

Structure

This gem inherits from the https://github.com/riboseinc/metanorma-standoc gem, and aligns closely to it.

Quickstart

Please see https://www.metanorma.com for instructions to get started.

If you are using a Mac, 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:

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

Usage

Using the metanorma CLI:

$ metanorma --type ogc a.adoc                   # output HTML
$ metanorma --type ogc --extensions html a.adoc # output just HTML
$ metanorma --type ogc --extensions xml a.adoc  # output Metanorma XML

Authoring

Please refer to the Metanorma-ISO documentation for general documentation.

Approach

Document model

The OGC document model is detailed here:

It is an instance of the StandardDocument model.

Document input

Document input to Metanorma is for the compilation of content into the Metanorma XML document.

The Metanorma-OGC processor supports AsciiDoc input.

AsciiDoc is selected has been selected as the authoring tool to generate the document model representation of OGC standards.

Similar to Markdown, AsciiDoc is a lightweight markup format, but combines the rigor and expressivity of DocBook. A number of editors (through plugins) support preview of AsciiDoc files, so textual content can be previewed without running the Metanorma toolchain.

The Metanorma processor automates numbering of headings, figures, tables etc, automatically generates references and citations, and the resulting output presentations.

Note
The Asciidoctor gem is used for AsciiDoc input parsing.

Document attributes

Common attributes

Metadata of the document is provided through AsciiDoc document attributes.

Metanorma-Standoc documents all common Metanorma document attributes. Where these preexisting metanorma attributes correspond to attributes already used by OGC in their Asciidoctor template, they are treated as synonyms of the Metanorma attributes. The attributes relevant to OGC documents include:

:edition:

The document version; e.g. 2.0.

:revdate:

The date the document was last updated.

:copyright-year: (OGC: :copyrightYear)

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 (mandatory). The permitted types are:

  • Standards

    standard

    Implementation Standard

    standard-with-suite

    Implementation Standard with Compliance Suite

    abstract-specification

    Abstract Specification

    community-standard

    Community Standard

    profile

    Profile / Application Profile

    best-practice

    Best Practices Document

  • Other

    engineering-report

    Engineering Report

    discussion-paper

    Discussion Paper

    reference-model

    OGC Reference Model

    user-guide

    User Guide

    policy

    OGC Policy Document

    guide

    Guide

    amendment

    Technical Amendment

    technical-corrigendum

    Corrigendum (errata) Changes to OGC Standards

    administrative

    Internal administrative documents

:status:

Document status/stage. The permitted types are:

rfc

OGC RFC (proposal)

candidate

Candidate Standard

published

Published

deprecated

Deprecated

retired

Retired

:committee:

The name of the relevant committee producing the document (mandatory). The legal values are: technical, planning, strategic-member-advisory

:subcommittee:

The name of the relevant subcommittee producing the document

:workgroup: (OGC: :workingGroup:)

The name of the relevant working group producing the document (mandatory)

:language:

The language of the document (e.g. en) (mandatory)

:published-date: (OGC: :publicationDate:)

The publication date for the document.

:issued-date: (OGC: :approvalDate:)

The approval date for the document.

:created-date:

The creation date for the document.

:received-date: (OGC: :submissionDate:)

The date at which the document was submitted to the standards body.

:uri:

The URI to which this standard is published.

:xml-uri:

The URI for the Metanorma XML as which this standard is published.

:pdf-uri:

The URI for the PDF as which this standard is published.

:doc-uri:

The URI for the DOC as which this standard is published.

:docnumber: (OGC: docReference)

The internal identifier referring to this document.

:draft:

If present, review notes are included in the Metanorma XML output; otherwise they are suppressed.

OGC-specific attributes

The following document attributes are specific to this document class:

:external-id:

The external identifier referring to this document.

:referenceURLID:

The identifier embedded into a document type-specific external URL.

:previous-uri:

URI of previous version of the document.

:subcommittee-type:

The type of the relevant subcommittee producing the document

:subcommittee-number:

The number of the relevant subcommittee producing the document

:workgroup-type:

The type of the relevant workgroup producing the document

:workgroup-number:

The number of the relevant workgroup producing the document

:keywords:

Comma-delimited list of the keywords associated with the document.

:submitting-organizations:

Semicolon-delimited list of the submitting organisations for this document. (The organisation names themselves may contain commas; e.g. University of Calgary, Canada; National Central University, Taiwan.

:fullname{_i}:

The full name of a person who is a contributor to the document. A second person is indicated by using a numeric suffix: :fullname:, :fullname_2:, fullname_3:, &c.

:surname{_i}:

The surname of a person who is a contributor to the document.

:givenname{_i}:

The given name(s) of a person who is a contributor to the document.

:role{_i}:

The role of a a person who is a contributor to the document. By default, they are coded as an editor; they can also be represented as an author.

OGC :editor:

corresponds to :fullname: with role = "editor"

Asciidoctor features specific to OGC

The metanorma-standoc gem documents the customisations of Asciidoctor markup common to all metanorma gems. The following markup is specific to this gem:

Section names

The Normative References section may be named just "References", reflecting OGC practice.

Preliminary elements

The following clauses are preliminary elements, and are moved into the frontispiece of the document (in Metanorma, the document preface):

  • Abstract

  • Keywords

  • Preface

  • Submitting Organizations

  • Submitters

The abstract is recognised as the first clause with an abstract style attribute:

[abstract]
== Abstract

xxx

The preface is recognised as the text between the Asciidoctor document attributes and the first Asciidoctor section title; it must not be given a section title of its own.

:received-date: 2019-01-01

.Preface

preface text

=== Submitters

Keywords and Submitting Organizations consist of lists. They are treated as document metadata, and are entered as a document attribute. The prefatory text introducing them is added automatically.

Submitters are treated as a table, contained in a section with the title Submitters:

=== Submitters

|===
|Name |Representing |OGC member

|Steve Liang | University of Calgary, Canada / SensorUp Inc. | Yes
|===

Examples

Unlike the normal case in Metanorma, examples can have captions:

[example]
.Example caption
====
Text
====

Recommendations, requirements, and permissions

Distinct recommendations, requirements and permissions are recognised in Metanorma Asciidoctor as tables whose first cell contains the text Recommendation, Requirement, Permission, optionally followed by a number (which is ignored in parsing; the elements are renumberd automatically in rendering.) These are currently constituted of two elements: an internal label, which is parsed as the first paragraph of the second table cell, and the body of the recommendation etc., which is parsed as the remainder of the second table cell.

[[recommendation1]]
|===
|Recommendation |/ogc/recommendation/wfs/2 +

If the API definition document uses the OpenAPI Specification 3.0,
the document SHOULD conform to the
<<rc_oas30,OpenAPI Specification 3.0 requirements class>>.
|===

Examples