Writing OGC documents using Metanorma

Document type and stage

Note

Document attributes listed below are unique to the processing of OGC documents in Metanorma.

For common document attributes, see Document attributes reference in general Metanorma author’s documentation. That page describes attributes that apply to all Metanorma flavors, not just OGC.

For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

:doctype:

Mandatory. Document type. Choices:

  • standard: Standard (a document subtype is necessary, see [ogc-docsubtype]) (default)

  • abstract-specification-topic: Abstract Specification

  • best-practice: Best Practice (a document subtype is necessary, see [ogc-docsubtype])

  • change-request-supporting-document: Change Request Supporting Document

  • community-practice: Community Practice

  • community-standard: Community Standard

  • discussion-paper: Discussion Paper

  • engineering-report: Engineering Report

  • other: Note, Primer, etc.

  • policy: Policy, Policy — Name Type Specification

  • reference-model: Reference Model

  • release-notes: Release Notes

  • user-guide: User Guide

  • white-paper: White Paper

:docsubtype:

Document subtype. Choices:

  • For doctype set to standard:

    • implementation: Implementation (default)

    • conceptual-model: Conceptual model

    • conceptual-model-and-encoding: Conceptual model and encoding

    • conceptual-model-and-implementation: Conceptual model and implementation

    • encoding: Encoding

    • extension: Extension

    • profile: Profile

    • profile-with-extension: Profile with extension

  • For doctype set to best-practice:

    • general: General (default)

    • encoding: Encoding

    • extension: Extension

    • profile: Profile

    • profile-with-extension: Profile with extension

:status:

Document status/stage. Synonym: :docstage:. Choices:

  • swg-draft: SWG Draft. This is the draft created after the TC approval and PC approval votes.

  • oab-review: OAB Review. This is the intended draft for the “OAB + OGC-NA Review”.

  • public-rfc: Public RFC. This is the draft for the (30 days) public comment period.

  • tc-vote: TC Vote. This is the intended draft for the TC adoption and PC adoptioin votes.

  • published: Published. This is the document intended to be published, after comments are handled with the TC chair (after tc-vote).

  • deprecated: Deprecated. This document has been deprecated.

  • retired: Retired. This document has been retired and no longer considered normative.

:keywords:

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

Note

Abbreviations are sometimes used to designate that a document has a certain document type, document subtype and document stage. This is a mapping from legacy OGC document values to the current normalized list:

“AS” Abstract Specification

Now :doctype: abstract-specification-topic.

“BP” Best Practice

Now :doctype: best-practice.

“CAN” Candidate Standard

Now :doctype: standard and :docstage: swg-draft.

“CC” Conformance Class

Not a standalone document, but a part of a document with :doctype: standard. No longer exists.

“CR” Change Request

Now :doctype: change-request-supporting-document; the actual Change Request is a database entry.

“CS” Community Standard

Now :doctype: community-standard.

“CP” Community Practice

Now :doctype: community-practice.

“DP” Discussion Paper

Now :doctype: discussion-paper.

“DP-Draft” Draft Discussion Paper

Now :doctype: discussion-paper with :docstage: swg-draft.

“IPR” Interoperability Program Report — Engineering Specification

Now :doctype: engineering-report.

“IS” Implementation Standard

Now :doctype: standard, :docsubtype: implementation.

“ISC” Implementation Standard Corrigendum

Now :doctype: standard, :docsubtype: implementation (TBD to indicate corrigendum).

“ISx” Extension Package Standard

Now :doctype: standard, :docsubtype: extension.

“Notes” Notes

Now :doctype: other, there is no specific type for “Notes”.

“ORM” OGC Reference Model

Now :doctype: reference-model.

“PC” Profile Corrigendum

Now :doctype: standard, :docsubtype: profile (TBD to indicate corrigendum).

“PER” Public Engineering Report

Now :doctype: engineering-report.

“POL” Policy

Now :doctype: policy.

“POL-NTS” Policy — Name Type Specification

Now :doctype: engineering-report, there is no specific indication for “NTS”.

“Primer” Primer

Now :doctype: other, there is no specific type for “Primer”.

“Profile” Profile

Now :doctype: standard, :docsubtype: profile.

“RFC” Request for Comment

Now :doctype: standard and :docstage: public-rfc.

“Retired” Retired document

This is a document stage indicated :docstage: retired.

“SAP” Standard Application Profile

Now :doctype: standard, :docsubtype: profile.

“TS”

Test Suite (TBD)

“WhitePaper” Whitepaper

Now :doctype: white-paper.

Author info

:committee:

Mandatory. Name of relevant committee producing the document. Use one of:

  • technical: Technical Committee

  • planning: Planning Committee

  • strategic-member-advisory: Strategic Member Advisory Committee

:subcommittee-type:

The type of the relevant subcommittee producing the document.

:subcommittee-number:

The number of the relevant subcommittee producing the document.

:workingGroup:

Mandatory. Name of relevant working group producing the document.

:workgroup-type:

Type of the relevant workgroup producing the document.

:workgroup-number:

Number of the relevant workgroup producing the document.

:submitting-organizations:

Semicolon-delimited list of the submitting organizations for this document. The organization names themselves may contain commas.

EXAMPLE: University of Calgary, Canada; National Central University, Taiwan

:editor:

Same as :fullname: alongside :role: specified as editor.

URIs and IDs

:external-id:

External identifier referring to this document.

:referenceURLID:

Identifier embedded into a document type-specific external URL.

:previous-uri:

URI of previous version of the document.

Mapping to OGC legacy AsciiDoc

Metanorma-OGC permits legacy OGC AsciiDoc template attributes, and are treated as synonyms of the corresponding Metanorma attributes:

OGC Metanorma AsciiDoc OGC legacy AsciiDoc

:copyright-year:

:copyrightYear

:workgroup:

:workingGroup:

:published-date:

:publicationDate:

:issued-date:

:approvalDate:

:received-date:

:submissionDate:

:docnumber:

docReference

:fullname:, with :role: = editor

editor

Markup

Sections

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 recognized as the first clause with an abstract style attribute:

[abstract]
== Abstract

My abstract...

The preface is recognized as the text between the AsciiDoc document attributes and the first AsciiDoc 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

Note
This subsection supplements Requirement, Recommendation, and Permission blocks in general Metanorma documentation.

For legacy reasons, a second Metanorma AsciiDoc syntax is permitted for recommendations, requirements and permissions.

These may also be recognized in Metanorma AsciiDoc as tables whose first cell contains the text Recommendation, Requirement, Permission, optionally followed by a number (which is ignored in parsing; the elements are renumbered 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>>.
|===

Reccomendations etc. with type=verification are crossreferenced and captioned as Recommendation Tests (Permission Tests, Requirement Tests), and are styled differently from recommendations proper. They are also excluded from the Table of Requirements in Word output [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.10].