Syntax for writing OGC documents using Metanorma

Document attributes

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 AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

:doctype:

Mandatory. Document type. Choices:

  • 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. Synonym: :docstage:. Choices:

  • rfc: OGC RFC (proposal)

  • candidate: Candidate Standard

  • published: Published

  • deprecated: Deprecated

  • retired: Retired

:keywords:

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

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>>.
|===