metanorma / metanorma-ogc

Metanorma processor for OGC documents

metanorma-ogc: Metanorma processor for the Open Geospatial Consortium document class

Functionality

This gem processes Metanorma documents following a template for generating OGC standards and documents.

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/metanorma/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/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-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.

• Metanorma-ISO general documentation: https://www.metanorma.com/software/metanorma-iso/

• Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/

Documentation

See Write Open Geospatial Consortium documents with Metanorma

Examples

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

• Document templates are available at the mn-templates-ogc repository.

metanorma-ogc's Issues

Using `pdf` output extension causes crash due to `puppeteer`?

bundler: failed to load command: metanorma (/Users/me/.rbenv/versions/2.6.5/bin/metanorma)
RuntimeError: internal/modules/cjs/loader.js:670
    throw err;
    ^

Error: Cannot find module 'puppeteer'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:668:15)
    at Function.Module._load (internal/modules/cjs/loader.js:591:27)
    at Module.require (internal/modules/cjs/loader.js:723:19)
    at require (internal/modules/cjs/helpers.js:14:16)
    at Object.<anonymous> (/Users/mulgogi/.rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/metanorma-0.3.18/bin/metanorma-pdf.js:4:19)
    at Module._compile (internal/modules/cjs/loader.js:816:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:827:10)
    at Module.load (internal/modules/cjs/loader.js:685:32)
    at Function.Module._load (internal/modules/cjs/loader.js:620:12)
    at Function.Module.runMain (internal/modules/cjs/loader.js:877:12)

From OGC: standardize front matter data elements (NOT READY)

The testing document has a front matter structure like this:

• Preface
  • Motiviation
  • Historical background
• Submitting organizations
• Submitters
• Abstract

In the OGC WFS document:

• Preface
• Abstract
• Submitters

In the OGC TCPNP document:

• Abstract

We will need to know what are the "permitted data elements" in front matter, and which ones are optional / mandatory.

Possibility of using WorldWeatherSymbols in Metanorma

@chris-little at the Met Office raised the issue of using https://github.com/OGCMetOceanDWG/WorldWeatherSymbols in Metanorma documents during the OGC DocTeam session.

It was said that we can either refer to a Unicode private plane (if a font supporting these symbols is included, such as from https://github.com/Unidata/MetPy), or we support their symbols.

I wonder if there is an easy way of supporting new symbols/icons.

Thoughts @opoudjis ?

Handling latexmath in stem blocks

OGC has a need to use latexmath in stem blocks. Since asciidoctor supports it I suppose we could too without much hassle.

Enable nested inline formatting

The WFS_FES asciidoctor is generating <tt><link target="x"/></tt>. The isodoc gem to date has assumed that inline formatting does not contain any other inline formatting; so the empty <link> element is passed through to the HTML and not parsed, instead of normal behaviour of it being parsed and made to display the target as its content if empty.

I am biting the bullet in isodoc, and making inline formatting (em, strong, sup, sub, tt, keyword, strike, smallcap) process any markup they are wrapping, rather than just passing it through.

The grammar does not currently permit this. I am inclined to leave the grammar alone, so there is a warning about such markup.

Apply OGC reference rendering style in references (modified LNCS)

From @ghobona:

OGC has historically used a derivative of the LNCS referencing style for the normative references. See example usage below.

• ISO: ISO 19101-1:2014, Geographic information — Reference model — Part 1: Fundamentals, International Organization for Standardization, 2005

• OGC: OGC 07-036r1, OpenGIS® Geography Markup Language (GML) Encoding Standard, Open Geospatial Consortium, 2016

I refer to it as a derivative because the document number is placed ahead of the title and the year is not placed in brackets.

I tried to create this same effect using the [[[id,label]]] approach of the metanorma-ogc template but failed.

So I ended up using regular anchors. See the file sections/clause_3_references.adoc in the document at the following link:

https://portal.opengeospatial.org/files/?artifact_id=86696

Note that the author-title separator is a colon.

Is it possible to create the same effect using the [[[id,label]]] approach of the metanorma-ogc template?

This is a great question and we've just started working on this area. Basically, a citation is created according to two things:

1. The metadata elements of the cited item.
2. The locality information within that cited item (optional, e.g., "Annex B").
3. The reference rendering style of the document.

We are currently working towards having a customizable way of determining item 3.

In the near term, we can implement this "OGC reference rendering style" (a LNCS-variant) in the code.

In the longer term, we will want to implement the "OGC reference rendering style" as some sort of CSL / CSL-superset definition to ensure all references are correctly rendered.

Thoughts @opoudjis ?

Admonition styling

The WFS FES document has a profusion of Admonitions (cautions); but I've just discovered that we've never assigned rendering to admonitions in the HTML CSS. (We have in the Word CSS.)

I propose to make HTML admonitions pale red, and otherwise identical to the markup of Notes. Once you approve, I will propagate this to the other gems' stylesheets.

Debug request: images not shown in Windows Word?

A user reported:

images are coming through fine in the html renders of the documents, but they aren’t visible in the word.doc file. The word file’s size implies that the figures are in there but maybe not in a format that can be displayed...
[...] I note that for a .gif image, is at least showing something, but it still isn’t correct.

I'm running the same document on macOS but they show up in Word.

This seems to be an incompatibility we have with Windows Word.

@CAMOBAP795 can you help debug / fix this? Thanks!

ToC disappearing when an image is included

Reported from OGC

The Table of Contents (on the left of the attached screenshot) is not being generated when an image is inserted at line 8113 of the file.

When I comment out the line, the Table of Contents is generated.

Update boilerplate text for `doctype` varieties

These are from https://github.com/opengeospatial/templates .

doctype == 'standard':

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

doctype == 'best-practice':

This document defines an OGC Best Practice on a particular technology or approach related to an OGC standard. This document is not an OGC Standard and may not be referred to as an OGC Standard. It is subject to change without notice. However, this document is an official position of the OGC membership on this particular technology topic.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

doctype == 'discussion-paper'

This document is not an OGC Standard. This document is an OGC Discussion Paper and is therefore not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, an OGC Discussion Paper should not be referenced as required or mandatory technology in procurements.

doctype == 'white-paper'

This document is not an OGC Standard. This document is an OGC White Paper and is therefore not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, an OGC White Paper should not be referenced as required or mandatory technology in procurements.

doctype == 'release-notes'

This document is not an OGC standard. This document provides release notes for an OGC standard. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

NOTE: We don't currently support white-paper and release-notes

From OGC: Remove the name of the committee (i.e. Technical) from the front cover

Machine-readable requirement example

In WFS 3 there is this requirement block:

Requirement 2
/req/core/root-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200.

The content of that response SHALL be based upon the OpenAPI 3.0 schema root.yaml and include at least links to the following resources:

* /api (relation type ‘service’)
* /conformance (relation type ‘conformance’)
* /collections (relation type ‘data’)

Is the following a good example of the textual representation?

[requirement,label="/req/core/root-success",subject="endpoint",obligation="shall"]
====

[description]
A successful execution of the operation SHALL be reported as a response with a HTTP status code 200.

[routine,run="CoreRoot"]
----
CoreRoot(success): HttpResponse
if (success)
  recommendation(label: success-response)
end
----

[requirement,label="success-response"]
--

[description]
---
The content of that response SHALL be based upon the provided OpenAPI 3.0 schema and include at least links to the following resources:

* `/api` (relation type "service")
* `/conformance` (relation type "conformance")
* `/collections` (relation type "data")
---

[specification,type="oapi30"]
======
'/':
  get:
    responses:
      '200':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/root'
            properties:
              type: array
              items:
                $ref: '#/components/schemas/link'
              match:
                - href: '/api'
                  rel: service
                - href: '/conformance'
                  rel: conformance
                - href: '/collections'
                  rel: data
          text/html:
            schema:
              type: string
======
--

====

Normative references showing ISO documents with double org name

A picture is worth more than 10 words, in this case.

[bibliography]
== References

* [[[ISO5127,ISO 5127]]], _Information and documentation — Foundation and vocabulary_

* [[[ISO15924,ISO 15924]]], _Information and documentation – Codes for the representation of names of scripts_

The Table of Contents is not showing

See the left-hand side of the following screenshot.

The source for this document is at the following URL https://portal.opengeospatial.org/files/?artifact_id=86696

Initially we thought the issue was caused by a specific image but now the issue persists even when the image is not included in the document.

Implement styling from metanorma-ogc-style

The design at this point: metanorma/metanorma-ogc-style@1361950

is good.

@opoudjis could you help implement this?

Thanks!

`:received-date:` not working, `:submissionDate:` working

:submissionDate: is supposed to be an alias to :received-date:, but giving the latter produces "XXX" while the former works properly.

:received-date: should work.

Use sentence case on titles and headers

The names of OGC standards are often written using a combination of upper and lower case e.g. GeoPackage, PipelineML, CityGML.

Currently the metanorma-ogc template uses all caps on titles and headers.

Please change the template to use sentence case on titles and headers.

Broken stylesheet: EXAMPLE

As shown.

Display OGC-specific items on HTML/Word output

"Warning" for policy documents (http://docs.opengeospatial.org/pol/05-020r25/05-020r25.html)

Warning
This document is an OGC Policies and Procedures Document. The document is subject to change based on membership requirements and motions. Please note that the OGC “Policies Related to OGC Standards” should be also be read. [http://www.opengeospatial.org/ogc/policies/directives]

Document stage: Approved for public release
Document subtype:
Document language: English

Submission Date: 2017-01-30
Approval Date: 2017-06-06
Publication Date: 2017-07-17
External identifier of this OGC® document: : http://www.opengis.net/doc/tcpnp/25.0
URL for this OGC® document: http://docs.opengeospatial.org/pol/05-020r25/05-020r25.html
Internal reference number of this OGC® document: 05-020r25

Additional Formats (informative):

We need links to other formats from the HTML version. (this is also useful for CSD)

Previous Version (informative): html

If we can add a URL to be linked from it?

Metanorma OGC compile error with SaasC (Windows)

Reported by @rggibb on Windows. The key message is the line:

1: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:76:in `populate_css'
C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:128:in `generate_css': undefined method `load_paths' for SassC:Module (NoMethodError)

On a Mac I was unable to reproduce the error. This seems to appear with any Metanorma file. Would this be related to the latest version of SassC perhaps missing the load_paths method?

For @CAMOBAP795 .

Full trace:

> metanorma -R iso-19170-cd-en-sections.html iso-19170-cd-en-sections.adoc
[relaton] Info: detecting backends:
[relaton] processor "relaton_gb" registered
[relaton] processor "relaton_iec" registered
[relaton] processor "relaton_ietf" registered
[relaton] processor "relaton_iso" registered
[relaton] processor "relaton_itu" registered
[relaton] processor "relaton_nist" registered
[relaton] processor "relaton_ogc" registered
ISO style: Initial section must be (content) Foreword
ISO style: Prefatory material must be followed by (clause) Scope
ISO style: Normative References must be followed by Terms and Definitions
ISO style: Document must contain at least one clause
ISO style: WARNING (Line 64): number not broken up in threes: 2018
No French Title Intro!
element "sections" not allowed yet; missing required element "preface" @ 62:11
element "p" not allowed here; expected element "clause" @ 62:28
element "p" not allowed here; expected element "clause" @ 64:47
element "p" not allowed here; expected element "clause" @ 65:47
element "p" not allowed here; expected element "clause" @ 66:47
element "p" not allowed here; expected element "clause" @ 67:47
element "p" not allowed here; expected element "clause" @ 68:47
element "p" not allowed here; expected element "clause" @ 69:47
element "sections" incomplete; missing required element "clause" @ 69:239
element "iso-standard" incomplete; missing required element "bibliography" @ 70:16
Traceback (most recent call last):
        29: from C:/tools/ruby25/bin/metanorma:23:in `<main>'
        28: from C:/tools/ruby25/bin/metanorma:23:in `load'
        27: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.2.7/exe/metanorma:20:in `<top (required)>'
        26: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.2.7/lib/metanorma/cli.rb:60:in `start'
        25: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/thor-0.20.3/lib/thor/base.rb:466:in `start'
        24: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/thor-0.20.3/lib/thor.rb:387:in `dispatch'
        23: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/thor-0.20.3/lib/thor/invocation.rb:126:in `invoke_command'
        22: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/thor-0.20.3/lib/thor/command.rb:27:in `run'
        21: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.2.7/lib/metanorma/cli/command.rb:34:in `compile'
        20: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.2.7/lib/metanorma/cli/compiler.rb:33:in `compile'
        19: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.2.7/lib/metanorma/cli/compiler.rb:29:in `compile'
        18: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.2.7/lib/metanorma/cli/compiler.rb:41:in `compile_file'
        17: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-0.3.15/lib/metanorma/compile.rb:20:in `compile'
        16: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-0.3.15/lib/metanorma/compile.rb:183:in `process_extensions'
        15: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-0.3.15/lib/metanorma/compile.rb:183:in `each'
        14: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-0.3.15/lib/metanorma/compile.rb:192:in `block in process_extensions'
        13: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-iso-1.3.4/lib/metanorma/iso/processor.rb:32:in `output'
        12: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/html_convert.rb:17:in `convert'
        11: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:170:in `convert'
        10: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:140:in `convert1'
         9: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/function/utils.rb:30:in `noko'
         8: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/nokogiri-1.10.4-x64-mingw32/lib/nokogiri/xml/builder.rb:254:in `with'
         7: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/nokogiri-1.10.4-x64-mingw32/lib/nokogiri/xml/builder.rb:254:in `new'
         6: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/nokogiri-1.10.4-x64-mingw32/lib/nokogiri/xml/builder.rb:295:in `initialize'
         5: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:141:in `block in convert1'
         4: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/nokogiri-1.10.4-x64-mingw32/lib/nokogiri/xml/builder.rb:377:in `method_missing'
         3: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/nokogiri-1.10.4-x64-mingw32/lib/nokogiri/xml/builder.rb:394:in `insert'
         2: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:144:in `block (2 levels) in convert1'
         1: from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:76:in `populate_css'
C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/isodoc-1.0.4/lib/isodoc/convert.rb:128:in `generate_css': undefined method `load_paths' for SassC:Module (NoMethodError)

Metanorma version:

> metanorma version
Metanorma 0.3.15
Metanorma::Cli 1.2.7
Metanorma::Standoc 1.3.4/IsoDoc 1.0.4
Metanorma::ISO 1.3.4
Metanorma::Iec 0.0.7
Metanorma::Ietf 1.0.6
Metanorma::Gb 1.3.4
Metanorma::Csd 1.3.3
Metanorma::Csand 1.3.3
Metanorma::Csand 1.3.3
Metanorma::M3d 1.3.3
Metanorma::Acme 1.3.3
Metanorma::Unece 0.2.4
Metanorma::NIST 0.2.4
Metanorma::Ogc 0.2.4
Metanorma::ITU 0.2.6
> gem list --local

*** LOCAL GEMS ***

addressable (2.6.0)
algoliasearch (1.26.0)
asciidoctor (2.0.10, 1.5.8)
asciimath (1.0.8)
bigdecimal (default: 1.3.4)
bundler (2.0.2, 2.0.1)
camertron-eprun (1.1.1)
cldr-plurals-runtime-rb (1.0.1)
cmath (default: 1.0.0)
cnccs (0.1.3)
concurrent-ruby (1.1.5)
csv (default: 1.0.0)
date (default: 1.0.0)
dbm (default: 1.0.0)
did_you_mean (1.2.0)
etc (default: 1.0.0)
faraday (0.17.0)
fcntl (default: 1.0.0)
ffi (1.11.1 x64-mingw32, 1.9.25 x64-mingw32)
fiddle (default: 1.0.0)
fileutils (default: 1.0.2)
gb-agencies (0.0.5)
gbbib (0.4.4)
gdbm (default: 2.0.0)
git (1.5.0)
html2doc (0.8.11, 0.8.10)
htmlentities (4.3.4)
httpclient (2.8.3)
iecbib (0.2.2)
ietfbib (0.4.6)
iev (0.2.2)
image_size (2.0.1, 2.0.0)
io-console (default: 0.4.6)
ipaddr (default: 1.2.0)
iso-639 (0.2.8)
iso-bib-item (0.4.5)
isobib (0.4.4)
isodoc (1.0.4, 0.10.0, 0.9.23)
isoics (0.1.7)
json (2.2.0, default: 2.1.0)
liquid (4.0.3)
metanorma (0.3.15, 0.3.12, 0.3.11)
metanorma-acme (1.3.3, 1.2.0, 1.1.4)
metanorma-cli (1.2.7, 1.2.0, 1.1.8)
metanorma-csand (1.3.3, 1.2.0, 1.1.5)
metanorma-csd (1.3.3, 1.2.0, 1.1.4)
metanorma-gb (1.3.4, 1.2.0, 1.1.5)
metanorma-iec (0.0.7)
metanorma-ietf (1.0.6, 1.0.3, 1.0.2, 1.0.1)
metanorma-iso (1.3.4, 1.2.0, 1.1.5)
metanorma-itu (0.2.6)
metanorma-m3d (1.3.3, 1.2.0, 1.1.5)
metanorma-mpfd (0.1.10)
metanorma-nist (0.2.4, 0.1.1, 0.0.9)
metanorma-ogc (0.2.4, 0.1.0, 0.0.9)
metanorma-rsd (1.1.4)
metanorma-standoc (1.3.4, 1.2.0, 1.1.9)
metanorma-unece (0.2.4, 0.1.0, 0.0.14)
mime-types (3.2.2)
mime-types-data (3.2019.0331)
mimemagic (0.3.3)
mini_portile2 (2.4.0, 2.3.0)
minitest (5.10.3)
multipart-post (2.1.1)
net-telnet (0.1.1)
nistbib (0.1.6, 0.1.5)
nokogiri (1.10.4 x64-mingw32, 1.8.5 x64-mingw32)
openssl (default: 2.1.2)
optout (0.0.2)
power_assert (1.1.1)
psych (default: 3.0.2)
public_suffix (3.1.0, 3.0.3)
rake (12.3.2, 12.3.0)
rb-fsevent (0.10.3)
rb-inotify (0.10.0)
rdoc (default: 6.0.1)
relaton (0.5.6, 0.4.0, 0.3.4)
relaton-bib (0.3.9, 0.2.1, 0.1.5, 0.1.3)
relaton-cli (0.2.0, 0.1.10)
relaton-gb (0.6.5, 0.5.0)
relaton-iec (0.4.8, 0.3.0)
relaton-ietf (0.6.6, 0.5.2)
relaton-iev (0.1.1)
relaton-iso (0.6.7, 0.5.0)
relaton-iso-bib (0.3.9, 0.2.2)
relaton-itu (0.3.5, 0.2.0)
relaton-nist (0.3.6, 0.2.1)
relaton-ogc (0.1.2)
roman-numerals (0.3.0)
ruby-jing (0.0.1)
ruby_deep_clone (0.8.0)
rubyzip (2.0.0)
sass (3.7.4)
sass-listen (4.0.0)
sassc (2.0.1, 1.12.1)
scanf (default: 1.0.0)
sdbm (default: 1.0.0)
sterile (1.0.14)
stringio (default: 0.0.1)
strscan (default: 1.0.0)
test-unit (3.2.7)
thor (0.20.3)
thread_safe (0.3.6)
twitter_cldr (4.4.4)
tzinfo (2.0.0)
tzinfo-data (1.2019.1)
unicode2latex (0.0.2)
uuidtools (2.1.5)
webrick (default: 1.4.2)
xmlrpc (0.3.0)
zlib (default: 1.0.0)

Spec index of tables, figures, requirements

Document identifiers for OGC references depend on stages?

Does the OGC document identifier take into account the document stage?

For example, relaton/relaton-iso#61 is an example of how ISO document identifiers depend on the stage.

• FDIS Stage: "ISO 11136:2014/FDAmd 1"
• DIS Stage: "ISO 3839:1996/DAmd 1"
• CD Stage: "ISO 16063-1:1998/CD Amd 2"
• WD Stage: "ISO/IEC 23008-1/WD Amd 1"
• AWI Stage: "ISO 10844:2014/AWI Amd 1"
• NP Stage: "ISO 18562-1:2017/NP Amd 1"

Right now, we only know they go like this:

• OGC 18-005r4

ping @ghobona @gbuehler @ogcscotts

Example captions

Examples in WFS_FES are captioned. There is no provision for title captions in Metanorma to date (because examples are not captioned in ISO), and example captions are currently ignored. @ronaldtse Are you ok for me to add support for title captions to OGC? And to Metanorma in general? If so, the caption might look a little odd in HTML CSS.

"Introduction" section goes missing in OGC

Given this header section:

.Preface

This document specifies...

[abstract]
== Abstract

This document specifies...

=== Introduction

The ...

The document is rendered with this ToC (noticed Introduction is now "1.1", which is wrong):

Moreover, if I change Introduction to this:

== Introduction

The ...

The entire section goes missing in the rendered HTML.

Perhaps there should be some "tag" like [preface], which we have in NIST, to deal with unnumbered clauses?

Terms and definitions: allow authors to import a term from a glossary

Very often a standards author needs to import a term from the OGC glossary.

It is however an annoyance to copy/paste/re-type/re-format the term, definition, source, notes and examples.

This ticket is to:

1. Establish a Metanorma AsciiDoc syntax to automate this process

2. Allow Metanorma to import a term into a document (TBX, RDF/SKOS, Metanorma Term...)

3. Allow the author to override a term from the glossary while maintaining a reference to the unmodified source.

4. The glossary can be “cited” and used as an authoritative source, i.e. “[SOURCE: OGC Glossary x.y version z]” (something like that)

5. If a term exists in the OGC glossary, and is being used in the document, but does not provide a reference to the term, Metanorma can produce a warning to that effect.

Change "copyright" boilerplate

To:

Copyright notice
Copyright (C) Open Geospatial Consortium
To obtain additional rights of use, visit http://www.opengeospatial.org/legal/

Monospace children not monospaced

As a result of #10, there are now instances in HTML of things like <tt><a>xxx</a></tt>. In the HTML CSS, a is assigned the normal body font, and this overrides the monospace font assigned to tt, as a more specific element. But that behaviour is wrong: all children of a monospace tag should remain monospace.

From OGC: Change table formatting to a uniform fill colour, and a single colour for the border and grid lines

From @ghobona

Ideally a uniform colour for the fill.
..and a single colour for the border and grid lines.

OGC documents place "conformance" before "normative references"

Image is self-explanatory.

1. Scope
2. Conformance
3. References
4. Terms & defs
   ...

Right now the section numbering is broken:

1. Scope
2. References
3. Terms & defs
4. Missing
5. Conformance
   ...

CAUTION text block missing top border in Word

As title.

Fix specs

The following specs are failing

Failures:
  1) Asciidoctor::Ogc converts a blank document
     Failure/Error:
       def insert_toc(intro, docxml, level)
         toc = ""
         toc += make_WordToC(docxml, level)
         if docxml.at("//p[@class = 'TableTitle']")
           toc += %{<p class="TOCTitle">List of Tables</p>}
           toc += make_TableWordToC(docxml)
         end
         if docxml.at("//p[@class = 'FigureTitle']")
           toc += %{<p class="TOCTitle">List of Figures</p>}
           toc += make_FigureWordToC(docxml)
     
     ArgumentError:
       wrong number of arguments (given 2, expected 3)
     # ./lib/isodoc/ogc/word_convert.rb:61:in `insert_toc'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:122:in `word_intro'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:106:in `word_preface'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:58:in `word_cleanup'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:43:in `toWord'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:37:in `postprocess'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/convert.rb:154:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_convert.rb:34:in `convert'
     # ./lib/asciidoctor/ogc/converter.rb:58:in `document'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/metanorma-standoc-1.1.5/lib/asciidoctor/standoc/utils.rb:96:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor/document.rb:1190:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor.rb:1521:in `convert'
     # ./spec/asciidoctor/base_spec.rb:44:in `block (2 levels) in <top (required)>'
  2) Asciidoctor::Ogc uses default fonts
     Failure/Error:
       def insert_toc(intro, docxml, level)
         toc = ""
         toc += make_WordToC(docxml, level)
         if docxml.at("//p[@class = 'TableTitle']")
           toc += %{<p class="TOCTitle">List of Tables</p>}
           toc += make_TableWordToC(docxml)
         end
         if docxml.at("//p[@class = 'FigureTitle']")
           toc += %{<p class="TOCTitle">List of Figures</p>}
           toc += make_FigureWordToC(docxml)
     
     ArgumentError:
       wrong number of arguments (given 2, expected 3)
     # ./lib/isodoc/ogc/word_convert.rb:61:in `insert_toc'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:122:in `word_intro'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:106:in `word_preface'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:58:in `word_cleanup'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:43:in `toWord'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:37:in `postprocess'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/convert.rb:154:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_convert.rb:34:in `convert'
     # ./lib/asciidoctor/ogc/converter.rb:58:in `document'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/metanorma-standoc-1.1.5/lib/asciidoctor/standoc/utils.rb:96:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor/document.rb:1190:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor.rb:1521:in `convert'
     # ./spec/asciidoctor/base_spec.rb:425:in `block (2 levels) in <top (required)>'
  3) Asciidoctor::Ogc uses Chinese fonts
     Failure/Error:
       def insert_toc(intro, docxml, level)
         toc = ""
         toc += make_WordToC(docxml, level)
         if docxml.at("//p[@class = 'TableTitle']")
           toc += %{<p class="TOCTitle">List of Tables</p>}
           toc += make_TableWordToC(docxml)
         end
         if docxml.at("//p[@class = 'FigureTitle']")
           toc += %{<p class="TOCTitle">List of Figures</p>}
           toc += make_FigureWordToC(docxml)
     
     ArgumentError:
       wrong number of arguments (given 2, expected 3)
     # ./lib/isodoc/ogc/word_convert.rb:61:in `insert_toc'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:122:in `word_intro'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:106:in `word_preface'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:58:in `word_cleanup'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:43:in `toWord'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:37:in `postprocess'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/convert.rb:154:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_convert.rb:34:in `convert'
     # ./lib/asciidoctor/ogc/converter.rb:58:in `document'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/metanorma-standoc-1.1.5/lib/asciidoctor/standoc/utils.rb:96:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor/document.rb:1190:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor.rb:1521:in `convert'
     # ./spec/asciidoctor/base_spec.rb:443:in `block (2 levels) in <top (required)>'
  4) Asciidoctor::Ogc uses specified fonts
     Failure/Error:
       def insert_toc(intro, docxml, level)
         toc = ""
         toc += make_WordToC(docxml, level)
         if docxml.at("//p[@class = 'TableTitle']")
           toc += %{<p class="TOCTitle">List of Tables</p>}
           toc += make_TableWordToC(docxml)
         end
         if docxml.at("//p[@class = 'FigureTitle']")
           toc += %{<p class="TOCTitle">List of Figures</p>}
           toc += make_FigureWordToC(docxml)
     
     ArgumentError:
       wrong number of arguments (given 2, expected 3)
     # ./lib/isodoc/ogc/word_convert.rb:61:in `insert_toc'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:122:in `word_intro'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:106:in `word_preface'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:58:in `word_cleanup'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:43:in `toWord'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_function/postprocess.rb:37:in `postprocess'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/convert.rb:154:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/isodoc-0.9.19/lib/isodoc/word_convert.rb:34:in `convert'
     # ./lib/asciidoctor/ogc/converter.rb:58:in `document'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/metanorma-standoc-1.1.5/lib/asciidoctor/standoc/utils.rb:96:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor/document.rb:1190:in `convert'
     # /home/travis/.rvm/gems/ruby-2.5.4/gems/asciidoctor-1.5.8/lib/asciidoctor.rb:1521:in `convert'
     # ./spec/asciidoctor/base_spec.rb:464:in `block (2 levels) in <top (required)>'
  5) Asciidoctor::Ogc uses user-specified Word stylesheets
     Failure/Error: html = File.read("spec/assets/test.doc", encoding: "utf-8")
     
     Errno::ENOENT:
       No such file or directory @ rb_sysopen - spec/assets/test.doc
     # ./spec/asciidoctor/base_spec.rb:524:in `read'
     # ./spec/asciidoctor/base_spec.rb:524:in `block (2 levels) in <top (required)>'
  6) IsoDoc::Ogc injects JS into blank html
     Failure/Error:
       def insert_toc(intro, docxml, level)
         toc = ""
         toc += make_WordToC(docxml, level)
         if docxml.at("//p[@class = 'TableTitle']")
           toc += %{<p class="TOCTitle">List of Tables</p>}
           toc += make_TableWordToC(docxml)
         end
         if docxml.at("//p[@class = 'FigureTitle']")
           toc += %{<p class="TOCTitle">List of Figures</p>}
           toc += make_FigureWordToC(docxml)
     
     ArgumentError:
       wrong number of arguments (given 2, expected 3)
     # ./lib/isodoc/ogc/word_convert.rb:61:in `insert_toc'

Supporting new OGC document stages (TBD)

We made a proposal to OGC on adopting these document stage codes.

UPDATED.

Definitive stages

• SWG Draft: swg-draft
• OAB Review: oab-review
• Public RFC: public-rfc
• TC Vote: tc-vote
• Published: published
• Retired: retired
• Deprecated: deprecated

These are based on this diagram from the OGC/ISO stage alignment presentation:

These are currently being considered by the OGC Document Team Subcommittee.

Match requirements with OGC models

Located here: https://github.com/riboseinc/metanorma-model-ogc/

Implement Metanorma for OGC documents

Document types

Standards

• Standard (with or without Compliance Suite)
  • Implementation Standard
  • Abstract Specification
  • Community Standard
  • Profile
• Best Practices Document

Others

• Engineering Report
• Discussion Paper
• Whitepaper
• User Guide
• Technical Committee Policy Directive
• "Informative/Educational" (?), such as "OGC Reference Model 08-062r7"

Deliverable stages

• SWG Work
• OAB Review
• OGC-NA Review
• Public Review
• Prepare for Approval
• TC Approval to Vote
• TC Vote
• PC Vote

(Will seek clarification on document stage codes)

Versioning

A semantic versioning is necessary. e.g. 1.0, 1.1, 2.0, etc. Maybe this is the "edition"?

Example deliverables

Despite differences in appearance (now), all of these should be presented according to the standard "Standard" format.

Standard: WCS

Standard: WKT

Non-standard: Testbed

Non-standard: GeoPackage

Non-standard: Ref model

Missing metadata elements in rendered output

In ogc-tcpnp:

http://docs.opengeospatial.org/pol/05-020r26/05-020r26.html

Category: OGC® Policy
Editor: Scott Simmons

Wrap sourcecode in Word

In Word, spaces are rendered as non-breaking in sourcecode. But that results in lines not wrapping, and therefore having lines not visible if they keep going past the right margin. Either CSS to force wrapping, or no non-breaking space in sourcecode in Word.

Sourcecode captions

In WFS_FES, sourcecode also has captions. As it turns out, isodoc caters for sourcedoc having captions, but metanorma-standoc in its parsing of Asciidoctor does not, so any sourcecode captions provided are being ignored.

Investigate compatibility of latest OGC AsciiDoc templates

OGC has released their latest AsciiDoc templates just yesterday at the 110th TC Plenary:
https://github.com/opengeospatial/templates

This task is to ensure that Metanorma works with these templates, and perhaps we should fork it to provide Metanorma attributes within the templates too (in the forked repo).

@ogcscotts @ghobona please feel free to provide input!

Support new document type: "Community Practice"

Latest document type mapping: (from @ghobona)

AS => Abstract Specification
BP => Best Practice
CAN => Candidate Standard
CC => Conformance Class
CR => Change Request
CS => Community Standard
CP => Community Practice
DP => Discussion Paper
DP-Draft => Draft Discussion Paper
IPR => Interoperability Program Report-Engineering Specification
IS => Implementation Standard
ISC => Implementation Standard Corrigendum
ISx => Extension Package Standard
Notes => Notes
ORM => OGC Reference Model
PC => Profile Corrigendum
PER => Public Engineering Report
POL => Policy
POL-NTS => Policy - Name Type Specification
Primer => Primer
Profile => Profile
RFC => Request for Comment
Retired => Retired document
SAP => Standard Application Profile
TS => Test Suite
WhitePaper => Whitepaper

The "D-" prefix means that a document is deprecated

1. CP — is there a special template / structure to be enforced for it? Or is it similar to any other kind of existing template?

It's similar to the other documents.

This is a master task that needs the following issues:

1. Update OGC document model in https://github.com/metanorma/metanorma-model-ogc (@opoudjis )
2. Implement CP as document type in Metanorma https://github.com/metanorma/metanorma-ogc
3. Support CP citation in Relaton (https://github.com/metanorma/relaton-ogc) and Metanorma (https://github.com/metanorma/metanorma-ogc)
4. Create a CP template in OGC templates (https://github.com/metanorma/mn-templates-ogc)

Update document types, subtypes and stages (CONFIRMED)

This is the latest document type list from @ogcscott . A "forward-looking" list, but will be confirmed.

Document types

• abstract specification topic
• best practice
• change request supporting document
• community practice
• community standard
• discussion paper
• engineering report
• other
• policy
• reference model
• release notes
• standard
• user guide
• white paper

Document subtypes for standard

• conceptual model
• conceptual model and encoding
• conceptual model and implementation
• encoding
• extension
• implementation
• profile
• profile with extension

Document subtypes for best practices

• (null) (i.e. no subtype, or just "general")
• encoding
• extension
• profile
• profile with extension

Current doctype => New or current doctype mapping

• abstract-specification => abstract specification topic
• approved-technical-baseline => Not a document type, remove.
• best-practice => best practice
• candidate-standard => (standard, in draft stage)
• change-request => "Change Request supporting document" (the actual Change Request is a database entry)
• community-practice => community practice
• community-standard => community standard
• conformance-class => Not a stand-alone document, rather a part of a document, remove
• discussion-paper => discussion paper
• draft-discussion-paper => discussion paper in draft
• extension-package-standard => (standard: extension)
• implementation-standard => (standard: implementation)
• implementation-standard-corrigendum => (standard: implementation, with corrigendum)
• interoperability-program-report => (engineering report)
• notes => other
• ogc-reference-model => reference model
• policy => (standard: policy)
• policy-specification => remove
• primer => other
• profile => (standard: profile)
• profile-corrigendum => (standard: profile, with corrigendum)
• public-engineering-report => (engineering report)
• recommendation-paper => (discussion paper)
• request-for-comment => (standard, in a draft stage)
• retired => a lifecycle stage, remove
• standard-application-profile => (standard: profile)
• test-suite => PENDING
• whitepaper => white paper

The document stage values are in another issue: #57

From OGC: Title Page needs version (and other items)

:major-version: 2
:minor-version: 3
:patch-version:
:doc-type: IS
:standard: GWML2

Updating:

:external-id: http://www.opengis.net/doc/{doc-type}/{standard}/{major-version}.{minor-version}

Thinking we could just add:

:version: 2.3

Thoughts?

Word templates for OGC documents

Not that we should use them, since they are not very pretty. Placed here to infer their structures.

OGC_Standard_Document_Template_10-176r8.docx

OGC_Implementation_Specification_template_building_on_OWS_Common.docx

From OGC: Remove mention of the Year after Open Geospatial Consortium on front cover

Machine readable requirements and recommendations

@ronaldtse You require machine-readable requirements, permissions, and recommendations. In WFS_FES these are mere tables, and I'm assuming from the tabular presentation that they consist of a title and a body, much like examples. In WFS_FES, they are given as e.g.:

[width="90%",cols="2,6a"]
|===
|Permission {counter:per-id} |/per/core/additional-status-codes +

Servers MAY support other capabilities of the HTTP protocol and, therefore,
MAY return other status codes than those listed in <<status_codes>>, too.
|===

I'm interpreting "Permission {counter:per-id}" as an auto-generated caption, just like tables and figures have captions, and /per/core/additional-status-codes is the permission label, separate from the table.

The markup will have to change from tables; for the time being, I will do that as postprocessing, grabbing any table with a first cell of "Requirement/Permission/Recommendation n", and transforming them into <permission id="permission-n"><name>...</name>....</permission>. But I'd rather they be entered as style attributes, e.g.

[[permission-n]]
[permission]
. /req/core/api-definition-op
====
The server SHALL support the HTTP GET operation at the path /api.
====

@ronaldtse, does that markup make sense to you?

Tables with merged cells are not showing

It appears tables that have merged cells are not shown correctly.

See the screenshots below. The following figure is how the metanorma-ogc template presents the Requirement 1 table.

The following figure is how asciidoctor presents the Requirement 1 table.

Alternative approaches for achieving the same effect through metanorma would be appreciated.

The source for the document is at https://portal.opengeospatial.org/files/?artifact_id=86696

Note that the source for Requirement 1 is in the file requirements/REQ001.adoc

Space Mono ligatures

The Space Mono font, used in many of our gems, is doing unwelcome ligatures: for example, fi, and more troubling, an arrow replacing />. Need to suppress ligatures in HTML CSS for monospace font in general, they defeat the purpose of having a monospace font.

Elimination of post-editing Word: Requirement representation

These very helpful issues have been raised by @rggibb . Thanks!

NOTE: We may want to split this issue.

Requirement Specification

Requirement 1 in Sec 5.2.1 on p13 of ISO 19170 .docx:

Source:

[[require-1]]
[.requirement,label=" "]
====
[.specification]
--
AA::
URI:: http://www.opengis.net/spec/DGGS/1.0/req/core/data_model
SPEC:: _A DGGS specification SHALL include DGGS Core Operations and a DGGS Earth Reference System based on Core Reference System._
--
====

Produces this:

Changes needed:

1. Requirement 1 is styled as admonitiontitle, so I can insert both a List of Figures and a List of Requirements after the Contents at the start of the document,
2. Set up a table style with header row in mid grey and remaining rows alternating no fill and light grey,
3. I can then move ‘Requirement 1:’ into the AA row of the table, delete the first column (containing AA, URI & SPEC), apply the table style from 2,
4. Repeat 3 for each Requirement.

Requirement Verification

cf A.1: Core-Data Model in Annex A, on p33 of ISO 19170 .docx

Source:

[[test-1]]
[.requirement,label="Core -- Data Model"]
====
 
[.verification]
--
AA::
URI:: http://www.opengis.net/spec/DGGS/1.0/conf/core/data_model
Title:: Core -- Data Model
Abbreviation:: core/data_model
Type:: Basic
Requirement:: Requirement {counter:req1}:
http://www.opengis.net/spec/DGGS/1.0/req/core/data_model
Reference Clause:: <<req-1>>
Test Purpose:: To verify the DGGS Specification conforms to the Core Data Model
Test Method:: Inspect documentation of the DGGS specification.
--
====

Produces this:

Changes needed:

1. Restyle ‘Requirement A.1: Core – Data Model’ from admonitiontitle to h3annex
2. Set up a table style with header row in mid grey and remaining rows no fill
3. Delete the word ‘Requirement’ and the line-break after the colon, move ‘A.1: Core – Data Model’ into the AA row of the table, delete the AA and merge the two cells in the header row into one cell, apply the style in 2) to the table
4. Repeat 3) for each conformance test
5. Edit the table of contents to include header 3 level entries, and update the TOC, so the conformance tests are listed in the TOC, and update the Table of Requirements so it only contains Requirements.

Other opportunities

1. You will have noticed that the Abbreviation in this case <core/data_model> occurs in 4x places, which seems a tad overkill I know, but that aside, these are:
2. Appended to http://www.opengis.net/spec/DGGS/1.0/req/ in the Requirement’s URI entry
3. Appended to http://www.opengis.net/spec/DGGS/1.0/conf/ in the Conformance test’s URI entry
4. As the Abbreviation in the Conformance test entry
5. As the name of the associated Requirement in the Conformance test entry
   .. and of course all of these have the same URI base of http://www.opengis.net/spec/DGGS/ plus <1.0/> which is also crying out for automation.
6. The Conformance label ‘Core – Data Model’ occurs in 2x places in the Heading for the Conformance test and as the Conformance Test’s Title entry.
7. The Reference clause, might be able to be inferred from where the include statement is in the text, but I’m not too fussed at having to place a named reference at the appropriate clause.

NOTE: In the header the asciidoc ‘--’ converts to an n-dash, but it converts to an m-dash elsewhere. I’ve not bothered to change this, and I’m not particularly fussy about it, but it seems a tad odd.

Update document-type and document-stage according to README

The README has been updated with the document-types and document-stages from https://github.com/riboseinc/metanorma-model-ogc/ .

This task is to:

1. Update the gem to support those; and also
2. Update the colors used for those document types/stages. See how it's done in metanorma-csd. Extra colors can be retrieved using https://coolors.co and entering the current colors.

Convert some sample OGC documents

Testbed: https://github.com/opengeospatial/D012-MapML_Engineering_Report

Standard: https://github.com/opengeospatial/WFS_FES

`doctype` is never explained in documentation

There is currently no "list" of doctype values.

I was only able to find them in the code:
standard standard-with-suite abstract-specification community-standard profile best-practice engineering-report discussion-paper reference-model user-guide policy guide amendment technical-corrigendum administrative

This issue is to provide documentation.