metanorma-ogc 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b4bc547f80aee864499bdc9d50864f3a11eb5bddae33a783dc170045a785bf22
+  data.tar.gz: 263220f48a361168f89d853975c96c9cec0c2f9c3044ae18ca9615bf74ba99d8
+SHA512:
+  metadata.gz: 5ef6af5cbf07a656265054c8d50403b8e3a622c8a786f6b8ffa78aa73c990646369818dd3263374b2d18ef4f7fb257d412ba555ae8d4d88e38d322acf1feaa58
+  data.tar.gz: cb737469297eb470b92478bbbcb2a5be63164a892348435b212ca076d21f9ada68aa200a6c67eef7b70b4d3fc9e2f5abef49cd7fdff5a6d7d18cf8923a970ab2

data/.gitignore

@@ -0,0 +1 @@
+.DS_Store

data/.hound.yml

@@ -0,0 +1,3 @@
+ruby:
+  Enabled: true
+  config_file: .rubocop.yml

data/.rubocop.yml

@@ -0,0 +1,10 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+AllCops:
+  TargetRubyVersion: 2.3
+Rails:
+  Enabled: true

data/.travis.yml

@@ -0,0 +1,16 @@
+dist: trusty
+sudo: false
+language: ruby
+rvm:
+  - 2.5
+  - 2.4
+  - 2.3
+  - ruby-head
+before_install:
+  - gem install bundler -v 1.16.1
+  - npm install -g puppeteer
+  - npm install
+  - unset _JAVA_OPTIONS
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ronald.tse@ribose.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+git_source(:github) {|repo| "https://github.com/#{repo}" }
+
+gemspec

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2018, Ribose
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,323 @@
+= metanorma-ogc: Metanorma processor for the Open Geospatial Consortium document class
+
+image:https://img.shields.io/gem/v/metanorma-ogc.svg["Gem Version", link="https://rubygems.org/gems/metanorma-ogc"]
+image:https://img.shields.io/travis/riboseinc/metanorma-ogc/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-ogc"]
+image:https://codeclimate.com/github/riboseinc/metanorma-ogc/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-ogc"]
+
+WARNING: This gem is still under development.
+
+== Functionality
+
+This gem processes Metanorma documents into the OGC document class.
+
+It provides the following functions:
+
+. Compiles Metanorma input into the Metanorma-OGC XML format
+. 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.
+. 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:
+
+[source,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:
+
+[source,console]
+----
+$ 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.
+
+* Metanorma-ISO general documentation: https://www.metanorma.com/software/metanorma-iso/
+
+* Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/
+
+
+////
+** http://asciimath.org[AsciiMathML] is 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.
+////
+
+
+== Approach
+
+=== Document model
+
+The OGC document model is detailed here:
+
+* https://github.com/riboseinc/metanorma-model-ogc[OGC document model]
+
+It is an instance of the
+https://github.com/riboseinc/metanorma-model-standoc[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.
+
+https://github.com/riboseinc/metanorma-standoc[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 https://github.com/riboseinc/metanorma-standoc[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:
+
+[source,asciidoc]
+----
+[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.
+
+[source,asciidoc]
+----
+: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`:
+
+[source,asciidoc]
+----
+=== 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:
+
+[source,asciidoc]
+----
+[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.
+
+[source,asciidoc]
+----
+[[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
+
+* link:spec/examples/rfc6350.adoc[] is an Metanorma AsciiDoc version of https://tools.ietf.org/html/rfc6350[RFC 6350].
+* link:spec/examples/rfc6350.html[] is an HTML file generated from the Asciidoctor.
+* link:spec/examples/rfc6350.doc[] is a Word document generated from the Asciidoctor.
+