Metanorma: Aequitate Verum

Document header and metadata

General

The header contains information about the document (metadata). You specify these metadata by using predefined document attributes, that look like this:

:document-attribute: some-value

Most of the attributes take a value, while others are simple flags without a value, like:

:draft:

Some of the metadata will be visible in your document, such as :title:, while others are not visible but still affect how your document is generated.

The order of attributes does not matter to Metanorma.

You can specify metadata about:

  • Authors: issuing organization, authors, and their location

  • Document info: language, document stages (draft, published, etc.) copyright holder, etc.

  • Dates: draft dates, revision dates, publishing date, copyright year, etc.

  • Identifiers: document numbers, ISBNs, URIs (Uniform Resource Identifiers)

Note
Other metadata influence how the document is generated and should only be used by advanced users. Please refer to the OGC document attributes.

At a minimum, you will need to specify:

  • Title

  • Metanorma document class as ogc

  • Document number

  • Document type, and optionally subtype

  • Document stage

  • Committee

  • Author or editor

Note
Please refer to reference documentation to see the full list of OGC-specific document attributes.
Note
In this section we use the document header from OGC 17-069r3 to explain.

Document-specific attributes and basic operations

These are the basic document attributes for OGC.

Example 1. Setting basic document attributes for OGC
= API - Features - Part 1: Core (1)
:docnumber: 17-069r3 (2)
:external-id: http://www.opengis.net/doc/IS/ogcapi-features-1/1.0 (3)
  1. OGC document title.

  2. OGC document number.

  3. OGC External ID for this deliverable.

These are operational concerns that are useful for the author.

  • :mn-document-class: must be set in order to set the flavor to OGC.

  • :mn-output-extensions: determines what output to be produced.

Example 2. Setting OGC-specific attributes
:mn-document-class: ogc (1)
:mn-output-extensions: xml,html,doc,pdf,rxl (2)
:local-cache-only: (3)
  1. Metanorma flavor. For OGC, enter ogc.

  2. Metanorma output formats. For OGC, supported formats are xml, html, pdf, doc and rxl.

  3. Metanorma option to store data cache in the current directory.

Document types and subtypes

OGC offers many different types of deliverables that differ in the level of consensus.

Some types, such as standard and best-practice have subtypes that must be set.

The type is to be set via these two attributes:

  • :doctype: for the document type

  • :docsubtype: for the document subtype, necessary for certain :doctypes:

Document types, set using the :doctype: attribute, include:

  • standard: Standard (a document subtype is necessary) (default)

  • abstract-specification-topic: Abstract Specification

  • best-practice: Best Practice (a document subtype is necessary)

  • 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

  • test-suite: Test Suite

  • user-guide: User Guide

  • white-paper: White Paper

Document subtypes, set using the :docsubtype: attribute, include:

  • 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

Example 3. Setting document type and subtype
:doctype: standard (1)
:docsubtype: implementation (2)
  1. OGC document type.

  2. OGC document subtype. Not all OGC deliverables have subtype.

Document stages and progress dates

OGC deliverables go through various stages of consensus building.

The document stage is set via the :status: attribute.

Values accepted by the :status: attribute include:

  • For an OGC standard and an abstract specification topic, it goes through the stages of: swg-draft, oab-review, public-rfc, tc-vote and approve.

  • An OGC community standard goes through the same stages as a normal standard, except swg-draft is replaced with work-item-draft.

  • All other types only have one draft stage and then goes to approved.

  • OGC deliverables can also be rescinded or retired but these are not discussed here.

Example 4. Setting document stage and progress dates
:edition: 1.0 (1)
:status: approved (2)
:received-date: 2019-07-11 (3)
:issued-date: 2019-09-09 (4)
:published-date: 2019-10-14 (5)
  1. OGC document edition. This is optional.

  2. OGC document status.

  3. OGC date of receipt.

  4. OGC date of issuance.

  5. OGC date of publication.

Authorship and other preface information

There are three types of authorship information:

  • The working group that created the document, this is set via the :committee: attribute.

  • The individual contributors that created the document, this is set via the :fullname: and :role: attributes. Additional contributors are set by suffixing the attribute with a _{n} where {n} is a sequential number after 1, e.g. For :fullname_2: use :role_2:.

  • The submitting organizations (active OGC members) that submitted this document (i.e. supported the adoption of the document), this is set via the :submitting-organizations: attribute as semicolon-delimited values.

Example 5. Usage of authorship information
:committee: technical (1)
:fullname: Clemens Portele (2)
:fullname_2: Panagiotis (Peter) A. Vretanos
:fullname_3: Charles Heazel
:role: editor (3)
:role_3: editor
:keywords: OGC API, ISO, ISO/TC 211, geographic information, Geospatial API (4)
:submitting-organizations: CubeWerx Inc.; Heazeltech LLC; Hexagon; ... (5)
  1. OGC committee. Typically technical for standards.

  2. Name of the individual contributor (author or editor).

  3. Role of author or editor. To set role of a :fullname_2: use :role_2:. If the role value is not provided, it is set to author by default.

  4. List of OGC keywords, comma-delimited.

  5. List of OGC members submitting this deliverable, semicolon-delimited.

Metadata references

Metadata defined as document attributes can be used to substitute values defined by putting the attribute in curly braces {attribute}. The reference will be replaced with the value in the rendered output.

Example 6. Using a document attribute for variable replacement
:architecture-dwg: OGC Architecture Domain Working Group

This document was prepared by the {architecture-dwg}.

renders as:

This document was prepared by the OGC Architecture Domain Working Group.