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:
$ 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.
-
Metanorma-ISO general documentation: https://www.metanorma.com/software/metanorma-iso/
-
Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/
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 anauthor
. - OGC
:editor:
-
corresponds to
:fullname:
withrole
= "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
-
spec/examples/rfc6350.adoc is an Metanorma AsciiDoc version of RFC 6350.
-
spec/examples/rfc6350.html is an HTML file generated from the Asciidoctor.
-
spec/examples/rfc6350.doc is a Word document generated from the Asciidoctor.